Quick guide to setting up a Ruby on Rails and PHP
web development environment on OSX 10.9


This tutorial is a step by step guide to setting up a basic Ruby/Rails and PHP web development environment from a fresh install of OSX 10.9 Mavericks. I've had to go through this process several times in the last few months, so I decided to write it down and share it so that it might help anyone going through the process for the first time. I do assume some basic knowledge of terminal commands and web development terminology, but hopefully not so much that it will be too confusing for a beginner.

The first thing I do is open Safari and download Google Chrome. Once you've installed Chrome, you can download whatever other OSX programs you like and install them to your Applications directory. I use the following, but you can pick and choose your favorites.

When you've installed everything you want for OSX (or nothing), fire up your choice of terminal and keep following.

Install Homebrew

Homebrew is a package manager for OSX that makes installing some of the tools we're going to need incredibly simple. Run the following line in your terminal to install.

1ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)"

You may be prompted to download the Xcode command line tools before this will work, so make sure to do so if you haven't already. Then hit any key to continue the Homebrew installation.

After it's finished installing, it will prompt you to run several commands to make sure everything is working and up to date.

1brew doctor
2brew update

Install MySQL

MySQL is popular open-source relational database management system. If you've done some back-end web development before, you've almost certainly used MySQL at some point. Even if you're just learning, it's a good thing to have installed anyway.

Besides, now that you've got Homebrew installed, installing MySQL is easy.

1brew install mysql

These are the start and stop commands for MySQL. You can create aliases for them in your .bash_profile if you find them hard to remember.

1mysql.server start
2mysql.server stop
3mysql.server restart

Go ahead and start the server, then run mysql to make sure it's working. You can exit the MySQL command line interface by running exit.

Install and configure Git

Git is a popular source code management system that many developers rely on heavily for revision control and collaboration. If you are working with a team, you should check with them to make sure they aren't using something similar like Subversion.

Again, thanks to Homebrew installing Git is very simple.

1brew install git

Once it's installed, you should set up some basic configuration settings.

1git config --global user.name "Your Name"
2git config --global user.email "your@email.com"

Ruby and Rails

This section will get you set up with the basics for Ruby and Ruby on Rails development on OSX. If you don't intend to work with Ruby or Rails, you can skip this section although I do recommend looking into them at some point.

Install rbenv

rbenv is a Ruby environment management tool that allows you to run multiple versions of Ruby seamlessly on the same computer. You'll need something like this or RVM if you plan on working on older Ruby 1.8.7 or 1.9.3 projects, or if newer projects you're working on require bleeding edge versions of Ruby or Rails.

Installation is simple.

1brew install rbenv ruby-build

Install Ruby

Once rbenv is installed, run this to see all available Ruby versions:

1rbenv install -l

Install the versions you'd like. I prefer to have at least one later version of 1.8.7, 1.9.3, and 2.1.2 on my development machine. Keep in mind that each of these may take several minutes to finish.

1rbenv install [version]

Set one specific Ruby version as your global default. I like to keep my global default set to a recent build so that my newer projects and small testing scripts are using an up-to-date version.

1rbenv global [version]

Install RubyGems

RubyGems is the standard way to manage gems (collections of Ruby code written by the community for thousands of common and not-so-common tasks). It is possible to install RubyGems with Homebrew, but I've run in to trouble with it before so a standard installation may be easier. You can download it from your browser or clone it from the repository.

Then in your terminal window, cd to the directory you downloaded the package to and then run the setup file with admin access.

1cd /path/to/rubygems
2sudo ruby setup.rb

Install Rails

Ruby on Rails is a very popular Ruby web framework that you will probably want to get to know. It's just a gem, like tons of other Ruby code, so you can install it very quickly now that you've got RubyGems.

1gem install rails

This will install the latest stable build for your currently selected version of Ruby. For Ruby 2 and higher, this will be Rails 4 for the time being. You can look through some of the help documentation for instructions on specifying exact versions.

PHP Development

This section will walk you through setting up a simple PHP web development environment on OSX. Even if you don't plan on being a PHP developer, you will almost certainly need to do some work in PHP at some point, so you should probably get used to some of the basic set up and configuration.

Apple used to make it very easy, with a Sites folder automatically being created in your /Users/username directory but in the last couple versions they've removed this featured and turned off PHP by default. Here's how to set everything back up.

Setting up a ~/Sites folder

To get the standard ~/Sites directory back, first go and create it.

1cd ~
2mkdir Sites

Next go to your apache2 user settings and create a configuration file for your OSX username.

1cd /etc/apache2/users
2sudo nano username.conf

Add this to the blank file, replacing username with your actual username.

1<Directory "/Users/username/Sites"
2    Options Indexes MultiViews
3    AllowOverride All
4    Order allow,deny
5    Allow from all

Save the file using Ctrl-o then exit nano with Ctrl-x.

The apache server should already be running, but to make it pick up the new configuration file we need to restart.

1sudo apachectl restart

You should now be able to access http://localhost/~username/ in your web browser to see a listing of the contents of the ~/Sites directory.

Turn on PHP

Now that your ~/Sites directory is working, you need to make it so that PHP scripts can be run from those directories. To do that, load the PHP5 module in the Apache settings.

1cd /etc/apache2
2sudo nano httpd.conf

Find and uncomment (remove the #) this line.

1#LoadModule php5_module libexec/apache2/libphp5.so

Do the same for this line if you'd like to set up VirtualHosts to make web development on multiple projects even easier.

1#Include /private/etc/apache2/extra/httpd-vhosts.conf

Save (Ctrl-o) and close (Ctrl-x) the file, then again restart Apache.

1sudo apachectl restart

You should now be able to see the results of PHP scripts in your ~/Sites directory. You can create a ~/Sites/phpinfo/index.php file to test.

1cd ~/Sites
2mkdir phpinfo
3cd phpinfo
4nano index.php

Add this line and save.

1<?php phpinfo(); ?>

Then direct your browser to http://localhost/~username/phpinfo and see if you get an output of your PHP configuration. If so, you're all set to start developing.

OSX Niceties

This section just covers a few nice-to-haves when developing on OSX.

Show .dotfiles in OSX Finder

To show the (normally hidden) files that begin with a . in the OSX Finder, run this command in your terminal.

1defaults write com.apple.finder AppleShowAllFiles -bool YES

This is helpful if you switch between the Finder and your terminal often and don't want to forget about some important files, but it can also be annoying as you will be able to see the .DS_Store file in every directory you visit.

You can switch out the YES for NO if you want to turn it off. Might make sense to store this as a shorter alias in your ~/.bash_profile.

Also note that Cmd-Shift-. will show hidden dotfiles in Open/Save Finder Dialog.

Set up text editor terminal alias

Unless you are using a terminal based editor like Vim or emacs, you may want to map a simple alias to your choice of OSX Text Editor. In this case, Sublime Text but you could do the same for TextMate or Atom or any other editor as well. Just add this line to your ~/.bash_profile and open a new terminal session.

1alias subl='open -a "Sublime Text 2"'


This should give a solid foundation for anyone interested in developing in Ruby or PHP on OSX 10.9 Mavericks. There are tons of other tools and gems that you will probably end up using, but now you are set up to begin exploring and installing whatever you may need.

If you have any questions, don't hesitate to contact me through this site.