Skip to content

Installation Instructions for OS X 10.8 Mountain Lion

Jump to bottom
tmiyajima edited this page Nov 12, 2012 · 5 revisions

This guide has been written for OS X 10.8 Mountain Lion, however the instructions will also work for Lion. They should also work on OS X 10.6 Snow Leopard as well, but this has not been verified.

A: Pre-Requisites

You will need a basic Ruby on Rails development environment in order to use Honolulu Answers. This means in addition to Ruby and Rails having access to git, heroku, foreman and postgresql. This will all be covered below.

_You are strongly encouraged to use Mac OS X or a Linux derivative to develop Rails applications. This is because many third-party gems are untested or undocumented to work on Windows. Honolulu Answers has been developed on a mixture of Mac and Ubuntu platforms. _ Having said that, if you would like to develop on Windows please document your setup and submit a pull request with Windows support.

If you have not worked on Rails projects before and need the basics, we recommend you install and test everything using this guide[1]. Honolulu Answers is built with Ruby 1.9.3 and Rails 3.2.

You will also need PostgreSQL server. If you are running OS X Server (a paid upgrade on the App Store), nothing needs to be done. For non-server versions of OS X, we recommend using the Heroku-supported Postgres.app.

The following services are used with Honolulu Answers, and an API key from each is required:

B: Install Honolulu Answers from command terminal

Step 1: Database Setup

  1. Launch command prompt
  2. Ensure PostgreSQL server is running. If you are using Postgres.app simply launch the application and look for the black elephant in the menu bar.
  3. Type: "createuser -h localhost -sd hnl"
  4. (optional): you can verify this has worked by connecting to the postgres server with 'psql -h localhost' and typing '\du' for a list of users. '\l' gives a list of databases and '\q' exits. See also: PostgreSQL documentation.

Step 2: Install Honolulu Answers Project

First, you will need to fork the Code For America repository and work off that, since if you pull direct from our repo you will be unable to push any changes back to github. You can do this by clicking 'Fork' on the repo page in the upper right hand corner of the screen. This will make a copy of the application code onto your github account, giving you write access so you can 'git push'.

  1. cd ~/[Project]
  2. Type: "git clone https://github.com/xxxxx/honolulu_answers.git" where 'xxxxx' is your github username.
  3. Type: "cd honolulu_answers"
  4. Setup the config variables: * There is a sample .env file in the root directory of the application called ".env.sample" (you can see it if you type 'ls -a'). For reference, it's https://github.com/codeforamerica/honolulu_answers/blob/master/.env.sample . * Create a copy of it by typing "cp .env.sample .env" * Open up this file in a text editor ('open -e .env') * Fill in the blanks with your own API keys.[4]
  5. Install qt dependency with Homebrew * Install homebrew: "ruby <(curl -fsSkL raw.github.com/mxcl/homebrew/go)" * Install qt: "brew install qt"
  6. Check you have at least 1.2.x of bundler with 'bundle -v'. To upgrade, first remove bundler with 'gem uninstall -ax bundler' and then reinstall with 'gem install bundler -v 1.2.1'
  7. Install required gems with 'bundle install'
  8. Type "rake db:create" to create the development database[5]
  9. Type "rake db:schema:load" to create the tables
  10. Type "foreman run rake db:seed"[6] to seed the database with some sample articles
  11. Type: "foreman run rails s" to start the server

Step 3: Launch site in browser - (http://localhost:3000/)

  1. Refresh the page if it doesn't connect at first

C: Making changes and pushing to GitHub, Heroku

GitHub setup

If you cloned the repository from a fork on GitHub, then the remote will already be set for you.[7] You can check by typing 'git remote -v'. You should get something like this:

origin https://github.com/xxxxxxx/honolulu_answers.git (fetch)
origin https://github.com/xxxxxxx/honolulu_answers.git (push)

Deploying on Heroku

Assumes you have made an account on Heroku.com.

  1. 'cd /path/to/honolulu/answers'
  2. 'heroku login'
  3. 'heroku create'
  4. 'git push heroku master'
  5. Heroku will give you a URL where Honolulu Answers has been published. Make note of this URL.
  6. If you are using Searchify as your IndexTank provider, you will need to install the addon onto your newly created Heroku deployment with 'heroku addons:add searchify:small'. More info here. This is a paid add-on.
  7. We use memcached for caching. To install the free memcached add-on type 'heroku addons:add memcache'
  8. We use New Relic for performance monitoring. Add it with 'heroku addons:add newrelic:standard'. The standard plan is free.
  9. Type 'heroku plugins:install git://github.com/ddollar/heroku-config.git'
  10. Push the contents of the .env file to Heroku with 'heroku config:push'
  11. Type 'heroku config:add LD_LIBRARY_PATH=lib/native'
  12. Setup the database on Heroku with 'heroku run rake db:setup'
  13. In your browser, go to the URL you made a note of earlier in step 5. (You did make a note of it, right?)

Using Git to develop on Honolulu Answers

  • By default, the Bash shell shows just the working directory. One easy way to get lots more info, such as which git branch you are currently on and whether any changes have been made, is to install ZSH and the plugin oh-my-zsh. Type (without the quotes):
  • Git, and VCS in general, works best when you use multiple branches to manage development. We use two main branches, 'master' and 'development'. We have another Staging server set up with Heroku which is used to test code in 'development'. If you're serious about using git to its fullest potential, consider adopting Git Flow

For City of Honolulu DIT Only:

Once you have set everything up, we will work on your files. This will mean adding us as collaborators on your GitHub repo and your Heroku account. Once the handover is complete in a couple of months time, you may revoke our direct access and we will contribute through pull requests to your repository on Github. We will also merge back any changes made during this time to the Code For America repository.

In order to mirror our setup, you will have to create a staging server. In short, this means:

  • Change the heroku remote name, so that instead of 'heroku' it's called 'production'. This will change your commands from 'git push heroku master' to 'git push production master'. Apart from the git commands, everything else will stay the same.
    • git remote rename heroku production
  • Creating a new Heroku instance to host the staging site.
    • 'heroku create'
  • Change the new remote name to 'staging'
    • git remote rename heroku staging[9]
    • You can check that all worked by typing 'git remote -v'.
  • Push some code to the staging site
    • 'git push staging development:master' (or if you haven't yet set up a development branch, 'git push staging master:master')
  • Continue from step 7 of 'Deploying on Heroku' above to set up the staging server. You will need to append '-a nameofthestagingapp' to each command, except the command in step 10.
  • Since you have already added the Searchify add-on to your production server, you do not need to do so again for the staging site. Simply set the Searchify config variable on the staging server to be the same as the one on production.
    • 'heroku config:add SEARCHIFY_API_URL=xxxxxx@xxx.xxx -a nameofthestagingapp'[10]
  • Change the environment on your Staging server to be 'staging', so that you can have different environment configurations, defined in config/environments/<environment_name>.rb.
    • heroku config:add RAILS_ENV=staging -a nameofthestagingapp

[1] Note that in Step 3, if you "skip to installing RVM," that means skipping installing Homebrew and Git, and going straight to Step 5).

[2] You may also use another IndexTank API provider, or even run your own instance of IndexTank if cost is an issue.

[3] Required for uploading avatars of user-submitted content (author_pic).

[4] Remove the angle brackets "<" and ">" and replace the text between them with your API keys

[5] If this gives an error with something like 'Invalid date time format 'UTC' for 'TimeZone', try rebooting your computer and trying again, to finalize the installation of Postgres.app.

[6] It will prompt you for an 'Admin email'. This is the email that will be used to login to the CMS control panel at 'http://localhost:3000/admin'

[7] If you need to add a new remote, you can do so with "git remote add "

[8] Mountain Lion prevents this script form changing the shell. If you wish for Terminal to always load ZSH, right click on your account name in System Preferences > Users & Groups, choose 'Advanced Options, and change your shell to '/usr/local/bin/zsh'.

[9] It has the same name as the old remote because we changed the previous one and freed up the 'heroku' name, so heroku saw the remote name 'heroku' was free and used that...

[10] You will probably want to change that name at some point, which can be done on Heroku.com. The name of the staging app is the bit which comes before 'herokuapp.com', something like fluffy-bunnies-888.

Clone this wiki locally