Dev environment on OS X

From Ocean Framework Documentation Wiki
Jump to: navigation, search

Make sure you are running Mac OS 10.10 (Yosemite) or later. All terminal commands are to be executed as a normal user, not as root except where indicated (by sudo). Use sudo only where indicated. Perform all installs in the order specified below.


  1. Download and install Xcode from the App Store.
  2. From inside Xcode install "command line tools". [Preferences -> Downloads]

In xcode 5.02, the CLT are not always visible as a download. Run the following command in a terminal to trigger the installation.

 xcode-select --install

The above step isn't necessary on Mavericks and Yosemite, on Os X 10.10 and xcode 7, Command line tools must be downloaded herefrom the apple developer site.


Go to the MacPorts site and install from the latest dmg installer. Remember to restart the terminal after this command:

 sudo port selfupdate
 sudo port install libtool
 sudo port install autoconf
 sudo port install automake


 sudo port install git

If the above breaks under El Capitan (Sierra should have no such problems) due to problems with installing Perl (caused by a MacPorts bug), try the following before the install:

 sudo port install mod_perl2 +perl5_22

Ruby Version Manager

 \curl -sSL | bash


 source ~/.rvm/scripts/rvm

Check that the following returns "rvm is a function":

 type rvm | head -n 1


Install the latest Ruby. Any version from 2.0.0 upwards will work, though we recommend the 2.3.1p112 which is the version installed by the Ubuntu 16.04 LTS ruby-full package. The following will install the latest stable ruby version (you might need to do a sudo rvm get head first):

 rvm install ruby --latest

NB: sudo should not be necessary; if it is, your installation is wrong.

Set the current ruby (assuming you just installed ruby 2.3.1):

 rvm use 2.3.1

Set the default ruby for new shells:

 rvm use 2.3.1 --default

Verify that this is successful by opening a new terminal window. The command rvm current should return 2.3.1.

RVM gemsets

You can think of gemsets as bags of ruby gems which can be associated, packaged and deployed with a particular project. You can switch between different gemsets when switching projects, or when upgrading to a new Rails version, or when experimenting with newly released gems, without risking any collisions between installed gems.

Activate gemsets for your user by typing:

 rvm user gemsets

If you have checked out any Rails projects, check that their associated gemset is activated correctly by cding to the project root. Each Rails project root has a .rvmrc script which automatically sets the gemset as you enter the directory. Inside a Rails project, the command rvm current should return something like ruby-2.3.1p112@rails-4.2.8. The actual Ruby and/or the Rails versions may differ, but there should be a gemset name after the @ character.


Nokogiri is always a pain to install on OS X. If you encounter installation problems under El Capitan (Sierra should have no such problems), try the following:

 gem install nokogiri -- \
 --with-xml2-include=/Applications/ \

Modify your ~/.bash_profile

The important sections of this file are the export statements for MacPorts and MySQL, and also the RVM snippet (which should be placed at the end of the file, after all export statements have been executed). The aliases, default editor and bash completion code are of course entirely up to you to use as you see fit.

You will find that the various installers you have run up to this point will have modified this file for you. The following is merely a cleaned-up version.

export PATH="/opt/local/bin:/opt/local/sbin:$PATH"
# Finished adapting your PATH environment variable for use with MacPorts.

# Bash completion.
if [ -f /opt/local/etc/profile.d/ ]; then
    . /opt/local/etc/profile.d/
# The port bash-completion >=2.0 requires bash >=4.1; please make sure
# you are using /opt/local/bin/bash by changing the preferences of your
# terminal accordingly. If your version of bash is too old, the script
# above will not modify your shell environment and no extended completion
# will be available.

# Make Atom the default editor
export EDITOR='atom -w'

# Shell stuff
alias ll="ls -l"
alias la="ls -la"

# Git
alias gs="git status"
alias ga="git add -A ."
alias gb="git branch"
alias gc="git commit"  

# DynamoDB Local
alias ddb_local="java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -inMemory"

# Chef-repo bash scripts
export PATH=/Users/pjotr/Documents/Projects/Ocean/chef-repo-public/bin:$PATH

export PATH="$PATH:$HOME/.rvm/bin" # Add RVM to PATH for scripting

[[ -s "$HOME/.profile" ]] && source "$HOME/.profile" # Load the default .profile

[[ -s "$HOME/.rvm/scripts/rvm" ]] && source "$HOME/.rvm/scripts/rvm" # Load RVM into a shell session *as a function*

MySQL and/or PostgreSQL

Try these installation instructions for MySQL using MacPorts on El Capitan.

Try these installation instructions for PostgreSQL using MacPorts on El Capitan.

DynamoDB Local

To run tests involving DynamoDB, which is heavily used in Ocean, you either need to use AWS DynamoDB directly using an AWS account, or, when working offline, you need a locally running clone of DynamoDB. Amazon provides just such a local clone for development purposes, AWS DynamoDB Local. Make sure you have Java Runtime Engine (JRE) version 6.x or newer installed (on the Mac, you might also have to install the JDK), then get DynamoDB Local from

Put it in a suitable location, then cd to its directory. You're now ready to start DynamoDB Local:

java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -sharedDb

Replace -sharedDb with -inMemory to run the DB in RAM.

You might want to create a shell alias to start DynamoDB Local. Enter the following in your .bash_login file (or similar):

# DynamoDB Local
alias ddb_local="java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -inMemory"

For more information about DynamoDB and ocean-dynamo, please refer to this link.


You might want to add the following to your Rails spec_helper.rb files, before the RSpec.configure block:

# DynamoDB table cleaner
CHEF_ENV = "master" unless defined?(CHEF_ENV)
regexp ="^.+_#{CHEF_ENV}_[0-9]{1,3}-[0-9]{1,3}-[0-9]{1,3}-[0-9]{1,3}_test$") 
cleaner = lambda { 
  c =
  c.list_tables.table_names.each do |t| 
      c.delete_table({table_name: t}) if t =~ regexp
    rescue Aws::DynamoDB::Errors::LimitExceededException
      sleep 1

Then, inside the RSpec.configure block:

config.before(:suite) { }
config.after(:suite) { }

This will remove only those test tables created by the specs on this particular machine and environment. This is designed to be completely safe even on AWS and in parallel with other machines. (NB: Ocean defines a CronJob which deletes all test tables nightly, so you don't have to.)

SSH Keys

Bottle.jpg NOTE: The OpenSSL version must be above 1.0

Create the ~/.ssh directory:

mkdir ~/.ssh
chmod 700 ~/.ssh

Generate a new SSH key:

ssh-keygen -t rsa -C ""

You can also of course move an existing key into the ~/.ssh directory. If you do, make sure you chmod it to 600.

Add your SSH key to the Mac OS X keychain:

ssh-add -K ~/.ssh/id_rsa

Now add your SSH key to GitHub using the following instructions (you can skip step 2):

Install FireFox needed for local testing

Chrome driver

Download the following archive and unzip it:

Put the unzipped file on your PATH (example: /usr/bin/)

Recommended editors for OS X