From be24d6f48ac6bac50e1ca9d47009ff1d0505fae7 Mon Sep 17 00:00:00 2001 From: Nick Ragaz Date: Thu, 23 Jan 2014 22:34:29 -0500 Subject: [PATCH] Update the OS X development documentation * Remove some outdated information from the guide * Add scripts/osx_dev to bootstrap a working development environment * Add a Brewfile to track binary dependencies --- Brewfile | 22 +++++++ docs/DEVELOPMENT-OSX-NATIVE.md | 50 +++++++++------- script/osx_dev | 106 +++++++++++++++++++++++++++++++++ 3 files changed, 155 insertions(+), 23 deletions(-) create mode 100644 Brewfile create mode 100755 script/osx_dev diff --git a/Brewfile b/Brewfile new file mode 100644 index 00000000000..8b327dc19fd --- /dev/null +++ b/Brewfile @@ -0,0 +1,22 @@ +# Install development dependencies on Mac OS X using Homebrew (http://mxcl.github.com/homebrew) + +# ensure that Homebrew's sources are up to date +update + +# add this repo to Homebrew's sources +tap homebrew/versions + +# install the gcc compiler required for ruby +install apple-gcc42 + +# you probably already have git installed; ensure that it is the latest version +install git + +# install the PostgreSQL database +install postgresql + +# install the Redis datastore +install redis + +# install headless Javascript testing library +install phantomjs \ No newline at end of file diff --git a/docs/DEVELOPMENT-OSX-NATIVE.md b/docs/DEVELOPMENT-OSX-NATIVE.md index 4e089252695..09e98bd92cf 100644 --- a/docs/DEVELOPMENT-OSX-NATIVE.md +++ b/docs/DEVELOPMENT-OSX-NATIVE.md @@ -6,6 +6,17 @@ OS X has become a popular platform for developing Ruby on Rails applications; as Obviously, if you **already** develop Ruby on OS X, a lot of this will be redundant, because you'll have already done it, or something like it. If that's the case, you may well be able to just install Ruby 2.0 using RVM and get started! Discourse has enough dependencies, however (note: not a criticism!) that there's a good chance you'll find **something** else in this document that's useful for getting your Discourse development started! +## Quick Setup + +If you don't already have a Ruby environment that's tuned to your liking, you can do most of this set up in just a few steps: + +1. Install XCode and/or the XCode Command Line Tools from [Apple's developer site](https://developer.apple.com/downloads/index.action). This should also install Git. +2. Clone the Discourse repo and cd into it. +3. Run `scripts/osx_dev`. +4. Review `log/osx_dev.log` to make sure everything finished successfully. + +Of course, it is good to understand what the script is doing and why. The rest of this guide goes through what's happening. + ## UTF-8 OS X 10.8 uses UTF-8 by default. You can, of course, double-check this by examining LANG, which appears to be the only relevant environment variable. @@ -17,7 +28,7 @@ $ echo $LANG en_US.UTF ``` -## OSX Development Tools +## OS X Development Tools As the [RVM website](http://rvm.io) makes clear, there are some serious issues between MRI Ruby and the modern Xcode command line tools, which are based on CLANG and LLVM, rather than classic GCC. @@ -35,7 +46,7 @@ RVM (below) can automatically install homebrew for you with the autolibs setting So, you will need to install Homebrew separately, based on the instructions at the website above, and then run the following from the command line: - brew tap homebrew/dupes # roughly the same to adding a repo to apt/sources.list + brew tap homebrew/versions # roughly the same to adding a repo to apt/sources.list brew install apple-gcc42 gcc-4.2 -v # Test that it's installed and available @@ -51,8 +62,6 @@ If you don't have RVM installed, the "official" install command line on rvm.io w curl -L https://get.rvm.io | bash -s stable --rails --autolibs=enabled -**IMPORTANT** As of this writing, there is a known bug in rubygems that will make it appear to not properly install. It's fibbing. It installs just fine. - ### Updating RVM If you do already have RVM installed, this should make sure everything is up to date for what you'll need. @@ -78,28 +87,25 @@ Either way, you'll now want to install the 'turbo' version of Ruby 2.0. OS X comes with Git (which is why the LibXML2 dance above will work before this step!), but I recommend you update to Homebrew's version: - brew install git # 1.8.2 is current + brew install git # 1.8.5.3 is current You should now be able to check out a clone of Discourse. ### SourceTree -Atlassan has a free GIT client for OS X called [SourceTree](http://www.sourcetreeapp.com/download/) which can be extremely useful for keeping visual track of what's going on in Git-land. While it's arguably not a full substitute for command-line git (especially if you know the command line well), it's extremely powerful for a GUI version-control client. +Atlassan has a free Git client for OS X called [SourceTree](http://www.sourcetreeapp.com/download/) which can be extremely useful for keeping visual track of what's going on in Git-land. While it's arguably not a full substitute for command-line git (especially if you know the command line well), it's extremely powerful for a GUI version-control client. ## Postgres 9.2 -**NOTA BENE** As I'm writing this, Postgres is known to have some sort of hideous security problem that is supposed to be patched Real Soon Now. Be careful! - OS X ships with Postgres 9.1.5, but you're better off going with the latest from Homebrew or [Postgres.App](http://postgresapp.com). ### Using Postgres.app [Instructions pending] - ### Using Homebrew: -Whereas Ubuntu installs postgres with 'postgres' as the default superuser, Homebrew installs it with the user who installed it as such...and yet with 'postgres' as the default database. Go figure. +Whereas Ubuntu installs postgres with 'postgres' as the default superuser, Homebrew installs it with the user who installed it... but with 'postgres' as the default database. Go figure. However, the seed data currently has some dependencies on their being a 'postgres' user, so we create one below. @@ -139,30 +145,28 @@ Homebrew loves you. brew install phantomjs -### Setting up your Discourse +## Setting up your Discourse - -## Check out the repository +### Check out the repository git@github.com:discourse/discourse.git ~/discourse cd ~/discourse # Navigate into the repository, and stay there for the rest of this how-to -## Loading seed data +### Loading seed data From the discource source tree: - + psql -d discourse_development < pg_dumps/development-image.sql +### What about the config files? -## What about the config files? +If you've stuck to all the defaults above, the default `discourse.conf` and `redis.conf` should work out of the box. -If you've stuck to all the defaults above, the default `discourse.conf` and `redis.conf` should work out of the box. - -## Install the needed gems +### Install the needed gems bundle install # Yes, this DOES take a while. No, it's not really cloning all of rubygems :-) -## Prepare your database +### Prepare your database rake db:migrate rake db:test:prepare @@ -170,11 +174,11 @@ If you've stuck to all the defaults above, the default `discourse.conf` and `red ## Now, test it out! - bundle exec rspec - + bundle exec rspec + All specs should pass -## Deal with any problems which arise. +### Deal with any problems which arise. Reset the environment as a possible solution to failed rspec tests. These commands assume an empty Discourse database, and an otherwise empty redis environment. CAREFUL HERE diff --git a/script/osx_dev b/script/osx_dev new file mode 100755 index 00000000000..d517548b9fb --- /dev/null +++ b/script/osx_dev @@ -0,0 +1,106 @@ +#!/bin/bash + +set -e # terminate the script if any command fails + +## Preflight ## + +# Create the log directory if it does not exist +if [ ! -x log ]; then + mkdir log +fi + +if ! echo $LANG | grep UTF &> /dev/null; then + echo "Your system language is not UTF-8; please check the value of \$LANG" + exit +fi + +if [ -x /usr/local/var/postgres ]; then + echo "A PostgreSQL data directory already exists at /usr/local/var/postgres; remove it to use this script" + exit +fi + +exec > log/osx_dev.log + +## Install Homebrew (http://mxcl.github.com/homebrew) and other dependencies ## + +if [ ! -x /usr/local/bin/brew ]; then + echo "Installing Homebrew..." + ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)" +fi + +echo "Installing development dependencies from Brewfile..." +brew bundle # Install development dependencies using Homebrew +gcc-4.2 -v # Check that GCC installed successfully + +## Install RVM and Ruby 2.0.0 with turbo patchset ## +echo "Installing RVM..." +curl -L https://get.rvm.io | bash -s stable --rails --autolibs=enabled +source ~/.rvm/scripts/rvm + +rvm get stable +rvm autolibs 3 # Tell RVM to install anything it's missing +rvm requirements # This will install baseline requirements that might be missing +rvm install 2.0.0-turbo # Now, install Ruby 2.0.0 with performance patches +rvm --create --ruby-version use 2.0.0-turbo # Use this Ruby as the default in this directory + +# Check that the correct version is installed and active +echo "Checking Ruby installation..." +ruby -v | grep 2.0.0 + +## Configure PostgreSQL (PostgreSQL was installed by Homebrew using `brew bundle`) ## +echo "Loading PostgreSQL..." + +# stop PostgreSQL if it's already running +if brew services list | grep postgres; then + brew services stop postgresql +fi + +export PATH=/usr/local/opt/postgresql/bin:$PATH # You may want to put this in your default path! +initdb /usr/local/var/postgres -E utf8 + +brew services start postgresql + +# Seed data relies on both 'postgres' and 'vagrant' users existing +echo "Creating PostgreSQL users..." + +# Postgres is starting in the background. If it's not started yet, try again in a second +until createuser --createdb --superuser postgres; do + sleep 1 +done +createuser --createdb --superuser vagrant + +# Obviously this password is not safe for production use +echo "Creating PostgreSQL databases..." +psql -d postgres -c "ALTER USER vagrant WITH PASSWORD 'password';" +psql -d postgres -c "create database discourse_development owner vagrant encoding 'UTF8' TEMPLATE template0;" +psql -d postgres -c "create database discourse_test owner vagrant encoding 'UTF8' TEMPLATE template0;" +psql -d discourse_development -c "CREATE EXTENSION hstore;" +psql -d discourse_development -c "CREATE EXTENSION pg_trgm;" + +## Start Redis (Redis was installed by Homebrew using `brew bundle`) ## +echo "Loading Redis..." + +# stop Redis if it's already running (e.g. an old version) +if brew services list | grep redis; then + brew services stop redis +fi + +brew services start redis + +## Load seed data ## +echo "Loading seed data..." +psql -d discourse_development < pg_dumps/development-image.sql + +## Install gems ## +echo "Installing gems..." +bundle install + +## Prepare your database ## +echo "Preparing the database..." +rake db:migrate +rake db:test:prepare +rake db:seed_fu + +## Run tests ## +echo "Done! Running tests..." +bundle exec rspec \ No newline at end of file