Sometimes we have to configure a new development machine, whether it is for ourselves or a friend. We often find that there are some little pieces of our environment that we have forgotten about or have neglected to document. This is my documentation for a ready-to-work development environment for Ruby on Rails.

About Me

I have been working with Ruby on Rails for several years (since 2009) and have tried various other platforms; yet always circling back to Ruby on Rails. In my early days, I developed on Ubuntu as I did not have nor could I afford an Apple. I moved back to a Windows machine and used my host operating system for my main development environment. I kept an Ubuntu server within a Virtual Machine (Oracle VirtualBox) where I would SSH into the VM and run any tasks. I used a shared network folder via Samba to access my files. While my environment was very productive, it didn't have the true native feel of a development environment. I got an Apple, where I now spend my days developing Ruby applications.

I also run and maintain several pet projects; one of which is Drifting Ruby. Some of the older apps that I use for different things around the house will need updating from time to time and might use an older version of Ruby with a different gem versions. So, having multiple Ruby versions and being able to switch them is very handy.

While it is not required, I do have several servers in my basement that I use as a testing/staging environment as well as a code repository for my projects. I also back up all of my work to an offsite location in the event of a destroyed home.

I come from a Systems Administrator background where I worked on Windows environments and Linux environments daily. As a Ruby on Rails developer, you should become comfortable with your Terminal as it can be a great tool.

About This Guide

By no means are the topics or recommendations covered in this guide best practices. Please let me know if you have found anything that I should be doing differently. However, I have found that these steps work great for my productivity and comfort. Not everything in this guide is Ruby on Rails specific, but the majority does touch on the installation and configuration of Ruby on Rails or the development environment that I enjoy working in. This guide is based on MacOS Sierra 10.12.4. It should work for previous versions. If you do find some issues, please let me know and I"ll see about updating this guide.


I have found that there are a few programs that makes life much easier whenever I setup a new development environment. Here are the basic applications that I feel is necessary for any new environment.

Homebrew - The missing package manager for OSX
iTerm2 - Alternative Terminal
Spectacle - Hotkeys for Window Movement and Placement. This is an absolute must have if you're using multiple monitors.
SublimeText - Preferred text editor
Atom or Visual Studio Code are great free alternatives
Google Chrome - Browser of choice


Most developers that use an Apple probably rely on Homebrew as their quick goto for installing available packages. I'm no different. Let's get Homebrew installed. For the rest of the guide, most of our work is done in the Terminal. Where necessary, I'll indicate if you need to run something as `sudo` or not. If you do not see `sudo` prepended by any of the commands, it's safe to say that it is not required and/or recommended.

/usr/bin/ruby -e "$(curl -fsSL"

We can then use Homebrew to install the rest of our software applications.


brew cask install iterm2


brew cask install spectacle


Sublime Text

brew cask install sublime-text


brew cask install atom

Visual Studio Code

brew cask install visual-studio-code


brew cask install google-chrome

Additional Packages

Now that we have our core development tools installed, we can start installing our services.


While most Ruby on Rails developers like using PostgreSQL for their database backend, I like and use MySQL. You can also use MariaDB if you wish which is very similar to MySQL.

brew install mysql

You can then start the MySQL service (and this will allow it to start whenever the computer is booted)

brew services start mysql

We then need to set our password for the mysql  server. Be sure to remember this password. We will set our password through the secure installation script that gets shipped with mysql .


You will be asked a series of questions. Other than the first question and setting the root password, I'll answer yes to the rest.

Apache (Optional)

phpMyAdmin is a handy and fairly light weight web interface to the MySQL server. However, it does rely on enabling Apache as well as PHP

By default, Apache  comes with OSX 10.12.4 (as well as other previous versions). To start the service, type the below in your terminal.

sudo apachectl start

PHP (Optional)

By default, the `PHP` module is included with OSX. However, it is not enabled. Edit the `httpd.conf` file.

sudo nano /etc/apache2/httpd.conf

Look for the following line (Use `CTRL + W` to do a search within `nano`) and uncomment the line (remove the pound infront of it). You kids may call it a hashtag, but I'm still oldschool.

LoadModule php5_module libexec/apache2/

Save the `httpd.conf` file. You can do this by typing `CTRL + X` within `nano`. It will prompt you to save, enter `y` and press enter (which will overwrite the existing file).

sudo apachectl restart


While `MySQL Workbench` is an absolutely great tool, I do not care for it. I prefer using `PHPMyAdmin` in my development environmen. I usually keep `PHPMyAdmin` opened in a different tab, but have recently found myself using it less and less.

Let's create a symlink to the `mysql.sock`.

sudo mkdir /var/mysql sudo
ln -s /tmp/mysql.sock /var/mysql/mysql.sock

Install `PHPMyAdmin`

brew install homebrew/php/phpmyadmin

Let's edit our `httpd.conf` again.

sudo nano /etc/apache2/httpd.conf

Another tool that I use very often is called `puma-dev`. This allows me to quickly access and spin up a Ruby on Rails application without having to manually start the web service. I have found that there is sometimes a conflict with the `puma-dev` service and `apache`. To avoid this entirely, I change the port that `apache` will listen on.

Look for the line `Listen 80` and change this to:

Listen 8888

At the very end of the `httpd.conf` file, copy and paste the following:

Alias /phpmyadmin /usr/local/share/phpmyadmin 
<Directory /usr/local/share/phpmyadmin/> 
  Options Indexes FollowSymLinks MultiViews 
  AllowOverride All 
  <IfModule mod_authz_core.c> 
    Require all granted 
  <IfModule !mod_authz_core.c> 
    Order allow,deny Allow from all 

Restart `apache`

sudo apachectl restart

Oh My Zsh

If you prefer to have a fancier shell than `bash`, you can use `oh-my-zsh`. Purely a preference and an optional step. I will say though that the little `x` if changes that needs to be commited to version control and letting me know at a glance what branch I'm currently working on is a great tool to have if you spend a lot of time in the terminal.

curl -L | sh

You'll then need to provide your user password to change your terminal to ZSH.


While OSX 10.12.4 does come with a Ruby interpreter, I do not like using my system ruby version. Instead, I use RVM as my Ruby Version Manager. Other ones like `rbenv` and `chruby` are fine. All three will act similar as far as keeping your ruby environments separate. At the time of this guide, `Ruby 2.4.1` is the latest MRI version. This is the version that we will be using.

brew install gpg 
gpg --keyserver hkp:// --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 
\curl -sSL | bash -s stable 
source /Users/$(whoami)/.rvm/scripts/rvm 
rvm install 2.4.1 
gem update --system

I often prefer to skip the installation of my gem documentation. I do this because it takes longer to download and install the gem. If I need to find the documentation of a gem, I'll usually look at the Github README of the gem or similar.

echo 'gem: --no-document' >> ~/.gemrc

Let's install Ruby on Rails!

gem install rails


Personally, since I use a privately hosted Gitlab environment for my version control, I install and configure `git` on my development machines. However, this is purely optional if you have your own way/method of version control.

Be sure to change your `USERNAME` and `EMAILADDRESS` to your own information.

brew install git git config --global "USERNAME" && git config --global "EMAILADDRESS"


In order to pull and push my code to my git repository, I authenticate my machine with the version control server via an authorized ssh key.

ssh-keygen -t rsa -C "EMAILADDRESS" && cat ~/.ssh/

Copy and paste the SSH Key into your Version Control SSH Key section.


Puma-dev is an amazing tool. It will spin up web servers so that you can quickly access your Ruby on Rails applications. For example, if I have a project called `testapp` under `~/Rails/testapp`, I can use `puma-dev` to create a link to this application. Even on a fresh reboot, I can go to `` or and it will launch my Ruby on Rails application. There is no need to go into your terminal to start the web service. You can also have multiple Ruby on Rails applications running at the same time with this. No more fuss with trying to find out which port is currently in use by another Ruby on Rails application.

For a video tutorial, check out

brew install puma/puma/puma-dev sudo puma-dev -setup puma-dev -install

`cd` into your Rails application and ENTER. We will then create our link with puma-dev. You can pass the optional -n NAME to customize the that will be linked.

puma-dev link -n testapp .

You now have a symlink created under `~/.puma-dev` where it references to your Ruby on Rails application. You can now visit the `` in the browser and it should load up.

ElasticSearch (Optional)

If you use ElasticSearch for full text searching, then here is the quick way to install it. ElasticSearch does require Java to be installed.

brew cask install java brew install elasticsearch brew services start elasticsearch

Redis (Optional)

If you will be using caching, sidekiq, or ActionCable, you will need Redis.

brew install redis
brew services start redis

ImageMagick (Optional)

If you upload images and resize them, you'll most likely use `minimagick`. A dependency of these tools is `ImageMagick`

brew install imagemagick

Pulling an Existing Project

I typically create a Rails folder in my home directory.

mkdir Rails cd Rails git clone <remote repo>

Cloning a repository from within my `Rails` folder, will create a new folder with that repository's code.

From here, you're ready to go with your new development environment!

Quick Notes of Advice

Within my Google Chrome Bookmarks Bar, I keep a few different things. My First thing is a folder in the bookmarks that keeps a shortcut to my `puma-dev` URLs. I also keep a bookmark to `http://localhost:8888/phpmyadmin` to quickly access `PHPMyAdmin`.