EC2 on Rails
Deploy a Ruby on Rails app on EC2 in five minutes
Main Page: http://ec2onrails.rubyforge.org
Code on Github: http://github.com/pauldowman/ec2onrails
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 areunique 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:
- Ready to deploy a Rails app with little or no configuration of the server required
- Optional Amazon Elastic Block Store (EBS) setup and support for MySQL database persistence.
- Automatic backup of MySQL database to S3 (EBS enabled: snapshots taken every 2 hrs; Non-EBS enabled: full backup nightly + incremental backup using binary logs every 5 minutes if not using )
- Capistrano tasks to customize the server image, archive and restore the database to/from S3, and more (available as a rubygem)
- Mongrel_cluster behind Apache 2.2, configured according to Coda Hale’s excellent guide
- Ruby on Rails 2.1.0, 2.0.2 and 1.2.6
- Ruby 1.8.6
- MySQL 5
- god configured to monitor apache or nginx, mongrel, mysql, memcached, drive space and system load
- Ubuntu 8.04 LTS “Hardy” base image built using Eric Hammond’s EC2 Ubuntu script
- SSL support
- Amazon AMI tools installed
- Apache or Nginx web proxies
- MySQL, Apache/Nginx, and syslog configured to use /mnt for data and logging so you don’t fill up EC2’s small root filesystem
- Automatically archives Rails and Apache logs to S3 nightly.
- 32-bit and 64-bit images available (supports all instance types, small to extra large).
- Created using a build file, full source is available (the EC2 on Rails script is run from Eric Hammond’s EC2 Ubuntu script)
- Can be used as a clustered Rails app running on multiple instances
- Automatically runs hourly, daily, weekly and monthly scripts if they exist in Rails application’s script directory
- Local Postfix SMTP mail server (only available from within the instance, not listening on external network interfaces)
Using the image
This documentation will be improved soon, for now hopefully this covers the basics.
The current AMI id’s are:
- ami-c9bc58a0 (32-bit)
- ami-cbbc58a2 (64-bit)
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
Within your rails directory, run
wget -q -O Capfile http://github.com/pauldowman/ec2onrails/raw/master/examples/Capfile wget -q -O config/deploy.rb http://github.com/pauldowman/ec2onrails/raw/master/examples/deploy.rb wget -q -O config/s3.yml http://github.com/pauldowman/ec2onrails/raw/master/examples/s3.yml
Be sure to customize those files and read the comments.
In your database.yml file, add
host: db_primary to the host of other database configuration options. After running “cap ec2onrails:server:set_roles” it will resolve to the instance defined in your Capistrano “db” role.
3. 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.
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.
4. 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:
Note, this will only work if you have an external ssh command in the path, it won’t work for most Windows users.
5. 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.
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 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.
You’ll mostly need just the following Capistrano tasks:
cap ec2onrails:ami_idsShows the AMI id’s of the images that match the current version of the gem.
cap ec2onrails:db:enable_ebsThis task will move the primary mysql database onto an Amazon Elastic Storage Block (EBS) volume. You can call this task with the optional SIZE parameter defined (defaults to 10 gigs) like
cap ec2onrails:db:enable_ebs <span class="caps">SIZE</span>=10
You should then specify your own volume (or the one created by this task) in your capistrano deploy.rb file like so:
role :db, “ec2-xx-xxx-xx-xxx.compute-1.amazonaws.com”, :primary => true, :ebs_vol_id => ‘vol-12345abc’
NOTE MySQL EBS is not enabled by default. You may call this task at anytime to move your MySQL over to EBS, but just make sure you keep track of the volume-id that is printed out by this task and use it to modify your deploy.rb file
cap ec2onrails:server:set_rolesCustomizes each instance for it’s role(s) (as defined in your Capistrano deploy.rb file). Run this after starting or stopping instances. For now this just makes sure that only the appropriate services (Apache, Mongrel, and/or MySQL) are running. Eventually this will customize settings for the running services also. Note that an instance can have more than one role. If there’s only one instance it will have all roles.
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
cap ec2onrails:db:archiveArchive the MySQL database to the bucket specified in your deploy.rb. This is for archiving a snapshot of your database into any S3 bucket. For example, you might want to do this before deploying.
cap ec2onrails:db:restoreRestore the MySQL database from the bucket specified in your deploy.rb For example, I use this to restore the current production data (from my actual production backup bucket) onto a staging server that has the current production version of my app. I then deploy the new version which tests migrations exactly as they’ll run on the production server.
To get a full list of the Capistrano tasks at any time type
cap -T from with your rails app root.
Building the image
The EC2 on Rails server image is built using Eric Hammond’s EC2 Ubuntu build script
Note that building your own AMI is not necessary, other options are:
- Use one of the public AMI’s and configure it at run-time (recommended).
- Re-bundle one of the public AMI’s and save it as your own (not recommended because you won’t be able to take advantage of any bug fixes or updates).
1. Start an EC2 instance that will be used to run the build script. The recommended AMI’s are Amazon’s public developer images:
32-bit: ami-f51aff9c 64-bit: ami-f21aff9b
2. Copy your certificate file and private key file to the EC2 instance ephemeral storage, using your ssh IDENTITY (key) file:
scp -i <em><span class="caps">IDENTITY</span></em> pk-<span class="caps">XXXXXXXXXX</span>.pem [email protected]_HOSTNAME_:/mnt/ scp -i <em><span class="caps">IDENTITY</span></em> cert-<span class="caps">XXXXXXXXXX</span>.pem [email protected]_HOSTNAME_:/mnt/
3. Copy the entire ec2onrails source folder EC2ONRAILS to the EC2 instance ephemeral storage, using your ssh IDENTITY file:
Note: make sure NOT to include a trailing slash on the ec2onrails directory name, rsync behaves differently when copying directories if there is no slash at the end of the folder name! After this step you should have a directory on the server named /mnt/ec2onrails (e.g. use /rails/ec2onrails not /rails/ec2onrails/ or /rails/ec2onrails/.)
rsync -rlvzcC —delete —exclude=‘output*’ —exclude=‘.git’ —rsh=‘ssh -i <em><span class="caps">IDENTITY</span></em>’ <em>EC2ONRAILS</em> [email protected]_HOSTNAME_:/mnt/
4. Using ssh, log in to the EC2 instance HOSTNAME using your ssh IDENTITY file:
ssh -i <em><span class="caps">IDENTITY</span></em> [email protected]_HOSTNAME_
5. On the server, run the build script with the appropriate arguments: (ARCH is either i386 or amd64)
ruby /mnt/ec2onrails/server/build \ —bucket ec2onrails \ —prefix ec2onrails-custom \ —arch <em><span class="caps">ARCH</span></em> —user <span class="caps">XXXX</span>-<span class="caps">XXXX</span>-<span class="caps">XXXX</span> \ —access-key <span class="caps">XXXXXXXXXX</span> \ —secret-key <span class="caps">XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</span> \ —private-key /mnt/pk-<span class="caps">XXXXXXXXXX</span>.pem \ —cert /mnt/cert-<span class="caps">XXXXXXXXXX</span>.pem
See the change log.
How to submit patches
Please read the 8 steps for fixing other people’s code. The source code can be checked out anonymously using:
git clone git://github.com/pauldowman/ec2onrails.git
(In alphabetical order)
Adam Greene Arpit Jain Barry Paul Ben Woosley Chris Nolan Ed Wagner Mark Lane Paul Dowman Pivotal Labs Randy Harmon Robert J. Berger Sebastian Johnsson (If you’ve contributed code and you’re not listed here I apologize, please send me an email!)
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.
Copyright 2007 Paul Dowman, http://pauldowman.com/ This is free software, and you are welcome to redistribute it under certain conditions. This software comes with ABSOLUTELY NO WARRANTY. See the file named COPYING for details.