diff options
Diffstat (limited to 'docs/installing/macos.md')
| -rw-r--r-- | docs/installing/macos.md | 155 |
1 files changed, 155 insertions, 0 deletions
diff --git a/docs/installing/macos.md b/docs/installing/macos.md new file mode 100644 index 000000000..6e1986d59 --- /dev/null +++ b/docs/installing/macos.md @@ -0,0 +1,155 @@ +--- +layout: page +title: Installing on MacOS X +--- + +# Installation on MacOS X + +<p class="lead"> + We don't recommend using OS X in production, but if you want to get + Alaveteli running on your Mac for development, these guidelines should + help. +</p> + +Note that there are [other ways to install Alaveteli]({{ site.baseurl }}docs/installing). + +## MacOS X 10.7 + +Follow these instructions to get Alaveteli running locally on an OS X machine. These instructions have been tested with Xcode 4.1 on OS X Lion (10.7). We do not recommend using OS X in production. + +**Note:** This guide is currently incomplete. Please help by posting issues to the [alaveteli-dev Google group](https://groups.google.com/group/alaveteli-dev) or by submitting pull requests. + +## Xcode + +If you are using OS X Lion, download *Command Line Tools for Xcode* from [Apple](https://developer.apple.com/downloads/index.action). This is a new package from Apple that provides the command-line build tools separate from the rest of Xcode. You need to register for a free Apple Developer account. + +**Note:** As of Xcode 4.2, a non-LLVM version of GCC is no longer included. Homebrew has dealt with it by [switching to Clang](https://github.com/mxcl/homebrew/issues/6852). However, you may encounter errors installing RVM. *Please report these on the [mailing list](https://groups.google.com/group/alaveteli-dev).* The following instructions have been tested with Xcode 4.1. If necessary, you can install GCC from Xcode 4.1 by running: + + brew install http://github.com/adamv/homebrew-alt/raw/master/duplicates/apple-gcc42.rb + +## Homebrew + +Homebrew is a package manager for OS X. It is preferred over alternatives such as MacPorts and Fink. If you haven't already installed Homebrew, run the command: + + ruby <(curl -fsSkL raw.github.com/mxcl/homebrew/go) + +Next, install packages required by Alaveteli: + + brew install catdoc elinks gnuplot gs imagemagick libmagic libyaml links mutt poppler tnef wkhtmltopdf wv xapian unrtf + + +### Install postgresql + +Alaveteli uses PostgreSQL by default. If you've tested Alaveteli with MySQL or SQLite, let us know in the [alaveteli-dev Google group](https://groups.google.com/group/alaveteli-dev). + + brew install postgresql + initdb /usr/local/var/postgres + mkdir -p ~/Library/LaunchAgents + cp /usr/local/Cellar/postgresql/9.0.4/org.postgresql.postgres.plist ~/Library/LaunchAgents/ + launchctl load -w ~/Library/LaunchAgents/org.postgresql.postgres.plist + +## PDF Toolkit + +[Download the installer package](https://github.com/downloads/robinhouston/pdftk/pdftk.pkg) and install. + +## Ruby + +### Install RVM + +RVM is the preferred way to install multiple Ruby versions on OS X. Alaveteli uses Ruby 1.8.7. The following commands assume you are using the Bash shell. + + curl -L https://get.rvm.io | bash -s stable + +Read `rvm notes` and `rvm requirements` carefully for further instructions. Then, install Ruby: + + rvm install 1.8.7 + rvm install 1.9.3 + rvm use 1.9.3 --default + +### Install mahoro and pg with flags + +The `mahoro` and `pg` gems require special installation commands. Rubygems must be downgraded to 1.6.2 to avoid deprecation warnings when running tests. + + rvm 1.8.7 + gem update --system 1.6.2 + gem install mahoro -- --with-ldflags="-L/usr/local/Cellar/libmagic/5.09/lib" --with-cppflags="-I/usr/local/Cellar/libmagic/5.09/include" + env ARCHFLAGS="-arch x86_64" gem install pg + +#### Update + +As of August 22, 2012 or earlier, you can install `mahoro` in Ruby 1.9.3 on OS X 10.7 Lion with: + + brew install libmagic + gem install mahoro + +## Alaveteli + +The following is mostly from [the manual installation process]({{ site.baseur l}}/installing/manual_install). + +### Configure database + +Creates Alaveteli databases and an `foi` user with password `foi`. + + echo "CREATE DATABASE foi_development encoding = 'UTF8'; + CREATE DATABASE foi_test encoding = 'UTF8'; + CREATE USER foi WITH CREATEUSER; + ALTER USER foi WITH PASSWORD 'foi'; + ALTER USER foi WITH CREATEDB; + GRANT ALL PRIVILEGES ON DATABASE foi_development TO foi; + GRANT ALL PRIVILEGES ON DATABASE foi_test TO foi; + ALTER DATABASE foi_development OWNER TO foi; + ALTER DATABASE foi_test OWNER TO foi;" | psql -h localhost template1 + +### Clone Alaveteli + +We don't want to vendor Rails, as it causes problems locally. + + git clone https://github.com/mysociety/alaveteli.git + cd alaveteli + git submodule init + + sed -i~ 's/\\[submodule "vendor\/rails"\\]//' .git/config + + sed -i~ 's/url = git:\/\/github.com\/rails\/rails.git//' .git/config + git submodule update + +**Note:** Due to Markdown bugs, the first `sed` command above does not display properly if it appears in blockquote. + +### Configure Alaveteli + +Copy the example configuration files and configure `database.yml`. + + cp -f config/general.yml-example config/general.yml + cp -f config/memcached.yml-example config/memcached.yml + cp -f config/database.yml-example config/database.yml + sed -i~ 's/<username>/foi/' config/database.yml + sed -i~ 's/<password>/foi/' config/database.yml + sed -i~ 's/ port: 5432//' config/database.yml + sed -i~ 's/ # PostgreSQL 8.1 pretty please//' config/database.yml + +### Bundler + +Install the gems and finish setting up Alaveteli. + + rvm 1.8.7 + bundle + bundle exec rake db:create:all + bundle exec rake db:migrate + bundle exec rake db:test:prepare + +## Troubleshooting + +### Ruby version + +Ensure you are using the latest versions of Ruby. For example, some versions of Ruby 1.8.7 will segmentation fault, for example: + +``` +/Users/james/.rvm/gems/ruby-1.8.7-p357/gems/json-1.5.4/ext/json/ext/json/ext/parser.bundle: [BUG] Segmentation fault +ruby 1.8.7 (2011-12-28 patchlevel 357) [i686-darwin11.3.0] +``` + +Running `rvm install 1.8.7` should install the latest Ruby 1.8.7 patch level. Remember to switch to the new Ruby version before continuing. + +### Rake tasks + +Remember to run Rake tasks with `bundle exec`. To run the tests, for example, run `bundle exec rake`. |