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
This commit is contained in:
Nick Ragaz 2014-01-23 22:34:29 -05:00
parent 01cd63fff7
commit be24d6f48a
3 changed files with 155 additions and 23 deletions

22
Brewfile Normal file
View File

@ -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

View File

@ -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.
## 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
@ -174,7 +178,7 @@ If you've stuck to all the defaults above, the default `discourse.conf` and `red
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

106
script/osx_dev Executable file
View File

@ -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