OS X setup

Setting up the OTW archive software on OS X Lion

These instructions assume you are comfortable with your shell of choice. They also assume that you've installed Xcode and therefore have the GNU toolchain. None of this needs to be run as root.

1. Install Homebrew or some other package manager. These instructions assume you have installed brew. To get brew:

/usr/bin/ruby -e "$(curl -fsSL https://raw.github.com/gist/323731)"

2. You'll need a more recent Ruby than the one Lion comes with. There are two competing ways of managing Ruby environments on Unixes these days: rbenv and RVM. If you're already using one of these, you're done. If not, you'll need to install one and get yourself rubied up. These instructions assume you're using rbenv. To install via brew:

brew install rbenv rbenv-gemset ruby-build

Follow the setup instructions on the rbenv page to get it into your shell environment. Then run rbenv to install a recent Ruby. We currently use 2.0.0, so you will probably want to use that to avoid any compatibility issues:

rbenv install 2.0.0-p451
rbenv rehash

3. Install git and some other software prerequisites:

brew install git imagemagick sphinx redis mysql elasticsearch090

Follow the brew startup instructions for redis, Elasticsearch & MySQL -- just copy and paste to set up the launch control daemon configs. These will look something like this:

To have launchd start mysql at login:
	ln -sfv /usr/local/opt/mysql/*.plist ~/Library/LaunchAgents
    Then to load mysql now:
    launchctl load ~/Library/LaunchAgents/homebrew.mxcl.mysql.plist

Then follow the instructions for setting up MySQL databases. MySQL is the most annoying of the packages you have to deal with here, but the brew instructions work. Make a note of the user name and password you've used to set up MySQL.

4. You can now simply clone the source if you want:

git clone https://github.com/otwcode/otwarchive.git

If you want to participate in the project and send pull requests the easy way, you should probably instead make yourself an account on GitHub if you don't already have one. Fork the repo! Get a copy of your repo locally using either the excellent GitHub for Mac client or the command line:

git clone git@github.com:YOURGITHUB/otwarchive.git
git remote add upstream git://github.com/otwcode/otwarchive.git

You add the original repository as a remote so you can track changes made to official repo.

5. cd to the project directory. You're now looking at a typical Rails app. It uses bundler to manage dependencies, so you can install those easily:

gem install bundler
rbenv rehash
bundle install

6. Configure MySQL.

cp config/database.example config/database.yml

Edit the database.yml file and give it the MySQL user/pass combo you'd like it to use. Test that your setup is working by running the rake tasks to build the db tables:

bundle exec rake db:create:all
bundle exec rake db:schema:load
bundle exec rake db:migrate	

7. Configure redis.

cp config/redis.example config/redis.yml

If you're not already using redis in other projects, change dev.ao3.org to localhost and move to the next step. If you are, read on.

Unfortunately, the redis initialization forces you to set up redis using a 'hostname:port' string instead of just taking a hash like you might expect. This doesn't let you specify which redis database to use, which if you're already got data in a redis instance is unacceptable. Let's fix that.

Edit config/initializers/gem-plugin_config/redis.rb. Replace these two lines:

redis_host, redis_port = redis_config[rails_env].split(":")
$redis = Redis.new(:host => redis_host, :port => redis_port)

With this one:

$redis = Redis.new(redis_config[rails_env])

Put something like this into your redis.yml. Your db numbers might vary.

test:
	:host: localhost
	:port: 6379
	:db: 17
development:
	:host: localhost
	:port: 6379
	:db: 16
production:
	:host: localhost
	:port: 6379
	:db: 16

8. Edit config/local.yml and add anything to it that you want to change from config/config.yml. The file must be present even if empty.

9. Run the app:

bundle exec rails server

If you're on Yosemite (OS X 10.10), you may need to use bundle exec rails server -d

You might now need to fix a YAML engine problem. If Rails eventually exits with a yaml/psych parse error, edit config/boot.rb and add this line after Bundler.setup:

YAML::ENGINE.yamler = 'syck'

Newer versions of Ruby are using a YAML engine that doesn't allow symbols in YAML files, and the OTW localization files are full of symbols. The syck engine is tolerant of symbols. Another way to solve this problem is to use rbenv to install an older Ruby. 1.9.0 and 1.9.1 should work, but will have bugs fixed in later versions of Ruby.

You can now visit http://localhost:3000/ in your browser of choice and see an empty local archive.

10. To seed your database and load the site styles, run

bundle exec rake db:otwseed
bundle exec rake work:missing_stat_counters
bundle exec rake skins:load_site_skins

You may need to add a persistence_token with a placeholder value to the entries in admin.yml and users.yml.

11. Now that you know you have a working install, you can install Pow and use nicer URLs like http://otwarchive.dev/. Recommended for anybody working on more than one rack app project at a time.

12. To set up your test database, run

bundle exec rake db:test:prepare

You'll need to edit redis-cucumber.yml to get redis to work with cucumber tests. Remove the line that says

    dbfilename log/redis-cucumber-dump.rdb