EC2 on Rails

Get Version

UPDATE: This project is no longer being maintained.

Deploy a Ruby on Rails app on EC2 in five minutes

EC2 on Rails is an Ubuntu Linux server image for Amazon’s EC2 hosting service that’s ready to run a standard Ruby on Rails application with little or no customization. It’s a Ruby on Rails virtual appliance.

If you have an EC2 account and can start EC2 instances you’re five minutes away from deploying your Rails app.

EC2 on Rails is opinionated software: the opinion is that for many rails apps the server setup can be generalized and shared the same way as the web application framework itself. For many people (Twitter, this isn’t for you) the server image can be treated the same way as other shared libraries. And if the day comes when your needs are unique enough that EC2 on Rails can’t be configured to work for you then you can bundle your own image from it or fork the build source and customize it.

But until then, why spend your time configuring servers?

Features of the EC2 image:

Using the image

This documentation will be improved soon, for now hopefully this covers the basics.

The current AMI id’s in the U.S. region are:

The current AMI id’s in the E.U. region are:

I will keep these images available for as long as possible, they will not be deleted for at least a few years.

1. Install the gem

sudo gem install ec2onrails

2. Add the config files to your Rails app

Put Capfile in the root of your rails folder, and put deploy.rb and s3.yml in the config folder.

Be sure to customize those files and read the comments.

Also, use the hostname “db_primary” in your database.yml file. After running “cap ec2onrails:server:set_roles” it will resolve to the instance defined in your Capistrano “db” role.

4. Start up one or more instances of the image.

There is nothing EC2 on Rails-specific here yet (though soon there will be a Capistrano task to do this for you), if you’ve started EC2 instances before you can skip this section. Otherwise, I’m not going to lie, this part is complicated and will take a lot more than 5 minutes the first time.

Read the running an instance section in Amazon’s getting started guide.

For the AMI id’s of the current images do cap ec2onrails:ami_ids from within the app that you configured in the previous step (they’re also listed earlier on this page).

NOTE: Only use the images that match the current version of the gem.

Please see the change log for release notes, and see the list of open issues.

As is standard for public AMI’s, password-based logins are disabled. You log in with your own public/private keypair.

Most basic things can be configured automatically by the Capistrano tasks, but if you want to you can login by ssh as a user named “admin” (has sudo ability) or as “app” (the user that the app runs as, does not have sudo ability). The Capistrano tasks automatically use the app user to deploy the app, and the admin user for server admin tasks that require sudo.

IMPORTANT: Double-check your firewall settings. Be sure that you haven’t allowed public access to any ports other than TCP 22 and TCP 80 (and possibly TCP 443 if you’re going to enable HTTPS). If you’re using multiple instances, be sure to allow them network access to each other.

5. Copy your public key from the server to keep Capistrano happy

This is a workaround for a quirk in Capistrano. Technically all you should need to connect to the server is the private key file, the public key is on the server. But for some reason Capistrano requires that you have both the public key and the private key files together on the client.

There is a Capistrano task that tries to fix this for you. From within the root of your rails app do:

cap ec2onrails:get_public_key_from_server

Note, this will only work if you have an external ssh command in the path, it won’t work for most Windows users.

6. Deploy the app with Capistrano

Now that the gem is installed, your deploy.rb is configured and you can start and stop EC2 instances, this is the only thing you’ll need to do from now on.

cap ec2onrails:setup
cap deploy:cold

Yes, it’s that easy! The setup task will set the server’s timezone, install any gems and Ubuntu packages that you specified in the config file, and create your database.

That’s it, your app is now running on EC2!!

Capistrano tasks

Capistrano is the most commonly used Rails deployment tool. It comes with many standard “tasks”, and the EC2 on Rails gem includes Capistrano tasks specifically for configuring the server instance.

Capistrano is run from the command-line using the “cap” command, with a task name given as an argument.

Commonly-used tasks

In addition to the cap ec2onrails:setup task, you’ll mostly need just the following Capistrano tasks:

Note that due to the way that Capistrano works all tasks are run against all hosts that are currently defined in the deploy.rb file. So if you start a new instance then add it to your deploy.rb you will need to run “cap ec2onrails:setup” again which will be run on all existing instances.

Database management tasks

To get a full list of the Capistrano tasks at any time type cap -T from with your rails app root.

Building the image

Building the image is not required, most people will simply use the prebuilt public image, but there is also a build script that builds the image. It’s meant to be called by Eric Hammond’s EC2 Ubuntu script.

Mailing lists

There are two Google groups, one for announcements (usually just new release announcements) and one for discussion.


Comments are welcome. Send an email to Paul Dowman or to the Google group.

If you find bugs please file them here or send me an email.

Change log

See the change log.

How to submit patches

Pleae read the 8 steps for fixing other people’s code.

The source code can be checked out anonymously using:

git clone git://

Send me a pull request on Github, submit a patch to the RubyForge Tracker or email me directly.


This code is free to use under the terms of the GPL v2.

If you find EC2 on Rails useful please recommend Paul Dowman at Working With Rails.

Paul Dowman, 17th September 2010
Theme extended from Paul Battley