Running your Rails apps on a Mac

I keep making the obviously false assumption that people know how to run Rails apps on a Mac.

If you’re starting from scratch have a look here: http://railsinstaller.org/#osx – I haven’t looked at it, but it looks like it will take a lot of pain away. This post is for people who have an existing app running on an old version.

The following assumes that you have some kind of Ruby installed and some kind of Ruby gems that came with it.

Also, you’ve already got some Rails code, that may be running an old version of everything.

Install XCode if you need to

Start up a terminal and type


If it gives you a command not found error then you need to download XCode from the App Store, fire it up, and then ask it to install the command line utilities. This can take a while, and google is your friend if you don’t know where to find things.

If you already have XCode then you just need to install the command line utilities, which are off on a menu somewhere.

Install RVM

gem install rvm

when it gets to the end of the install it will tell you what to do to your shell environment to run rvm properly. DO IT. 🙂 For reference see https://rvm.io/ If you are unfamiliar with getting things to run in the active shell after altering the shell startup commands, just close the terminal and start a new one, life’s too short.

Install the Ruby you need

In this exercise we want Ruby 1.8.7, so …

rvm install 1.8.7

Eventually it will finish and tell you the version it installed, e.g. ruby-1.8.7-p352

You may encounter some errors, where Apple have kindly set the default C compiler not to be the old GNU ‘C’ compiler but their llvm one. Cut the error message out and paste it into Google, then do what it says. 

These instructions might say that it can’t find the command that you put into the environment variable, in which case use whereis cc to tell you where the cc command is.

Any other problems, use the more command or an editor to browse the log file it says

Create a .rvmrc file in your Rails root

Let’s assume the Rails app is called brightstuff. In the root of your Rails app type

ls .rvmrc

If it finds something, have a look and see what it says, for the purposes of this exercise I’m assuming the file isn’t there. Type the command

cat “rvm use [email protected]” > .rvmrc

Change brightstuff to the name of your app.


cd ..

cd –

This takes you up and then back to the directory you just added the rvmrc to. If you have installed RVM correctly it will ask you if you want to use the .rvmrc. Say yes.


gem install bundler

bundle install

This will set all the gems up for you in this version of Ruby, in a group named after your app.

Some people don’t use the gemset (which we have named brightstuff) and rely on bundle exec, but I’ve found this to be pretty bomb proof.

You can also install gems independently of the Gemfile used by bundler, I typically install things like powder (see below) like this, because they aren’t needed in any context other than development.

Start the Rails app

As is standard, you can start a development version of the app with:

bundle exec script/server

This will start the app on http://localhost:3000, you can use /etc/hosts and various tools (go look for them) to alias them, and start things on different ports.

Other things

I use the pow utility and it’s friend the powder gem to run my apps. http://pow.cx/

Rails for Designers

This is a short post to help designers who aren’t familiar with Rails understand their way around it enough to change things and work with developers. It assumes that you know CSS and HTML and aren’t scared of HTML that has embedded code in it.

The structure of a Rails app

Rails is a Model/View/Controller system. 

  • Models are business logic, and storing things in databases
  • Views are displaying the contents of the models
  • Controllers co-ordinate the Model and the View

Here is a picture of the directory structure of a Rails app:

The files you care about live under app and public:

And views also breaks down like this:

This application has an extra top-level directory, artwork, that isn’t standard. I used it to keep the artwork and design files under version control.

What the directories do:

  • Public. This is where the root of the application is for static content like CSS and JavaScript files.
  • App/Views. This is where the files are stored for rendering dynamic content from the application.
  • App/Views/Layouts. This is where the templates that surround the dynamic content are stored.

The example we show here is from before Rails introduced the performance enhancement of the asset pipeline, it complicates things a little and I will discuss it later. What I want do do first is explain the principles.

What things do

A layout file looks something like this:

<!DOCTYPE html>




  <%= stylesheet_link_tag :all %>

  <%= javascript_include_tag :defaults %>

  <%= csrf_meta_tag %>



  <div id=”header”>

    <div class=”span8 offset8”>


        <a href=”/”><img src=”/images/favorbite-logo.png” alt=”Favorbite logo”></a>


   <%= yield :header %>



    <%= yield %>



This is a very simple wrapper. It’s HTML 5, of course. The <%= %> tags are used to embed code. The :all in stylesheet link tag lets us include all of the files in the public/stylesheets directory without having to specify them individually, or you can include them one by one if you need to. This changes with the asset pipleline (but let’s not worry about that now).

You can also just put in plain old HTML code to include whatever CSS you like, the helpers are a convenience and also help with cacheing and other wondrous magic web things. 

You can see two lines that I have made bold. Each contains the word yield. This is a Ruby construct that you can find out more about if you’re interested. The one that doesn’t have any arguments will render the appropriate dynamic content file. The one with :header will render any content that is in a block that has that name. For example

Hello, this is ordinary content

<% content_for :header do %>
   This will appear where the yield :header tag tag is, or not appear at all if there isn’t one.
This is how you define a block, using ‘do’
<% end %>
If we carry on here it will just add into the main text.

<%= “the string here will show in the text, without the = sign nothing will happen, the results of any Ruby code need %= to show” %>

Working out what gets displayed

Rails apps have routes go to controllers, and from there to the view depending on what the controller decides to do to render the request. The surrounding layout is set by the controller. For example http://myapp.com/chickens/1/edit is asking the router to find a controller called chickens, and call the method edit in it. This will then find the chicken with ID 1 and render it to be edited if all goes well.

The dynamic code for the edit will be in app/views/chickens/edit.html.erb (ERB being a way of embedding Ruby code), inside that file you may find code that looks like this:

<%= render :partial => “form” %>

Partials a little chunks of reusable code, because no directory was given it will be assumed to be in the same directory as the other chickens code, here app/views/chickens/_form.html.erb

The convention for a partial is it has a leading underscore in its name. If the controller doesn’t explicitly say what dynamic content to render the file that matches the route will be used:

  • …/chickens – This will go to index method and will look for a file called index
  • …/chickens/1 – This will try and show the chicken with ID 1 – method/view called show
  • …/chickens/new This will render a form where you can create a new chicken
  • …/chickens/1/edit Guess!

When you save a new chicken you land in the method create, when you update an existing chicken you land in the method update. If these methods succeed the convention is that it puts a flash message saying it succeeded and takes you to the show method. Sometimes you will need to look in the controller code to unpick this.

For example if you see:

render :action => “edit”

It will use the edit file to render, rather than whatever the default one would be for the method you are in.

Picking the layout

If the controller doesn’t explicitly set a layout it will use the one defined in app/views/layouts/application.html.erb.

Configuration by convention

As you can see Rails uses convention to say where things are and you don’t have trawl through configuration files (Java) or wade through heaps of confusing code where it’s hard to work out where the application ends and the data begins (PHP guys, looking at you here). 

The asset pipleline

This was introduced in Rails 3.2. There is an extra directory under app called assets. Rather than repeat the documentation I suggest you go here to find out how it works.

I hope this helps. As always if I have erred or not explained things to your satisfaction, please contact me and I will do my best to explain it better or correct any mistakes.

Thanks for reading.

© 2020 Francis Fish

Theme by Anders NorénUp ↑