Deploying your Rails application

The following guide makes several assumptions about how you’re developing and planning to deploy your Rails application. Mileage may vary. If you have any issues or can offer improvements to this process, please help us maintain this documentation site with the appropriate changes.

We’re going to make the following assumptions.

• You have SSH installed on your local machine (where you’ll be deploying from)
• You have Capistrano installed on your local machine. (gem install capistrano)
• You are running a revision control system, such as git or subversion, that your Boxcar can connect to and export your application’s source code.
• You’re using Rails migrations for managing your database schema.

If this matches you, let’s move forward. If not, contact support to discuss alternative ways to deploy your Rails application on Boxcar.

Step 1: Connect and install gems

To make sure that Capistrano doesn’t complain when you’re ready to deploy, you will need to connect to your Boxcar using SSH at least once (as root):

ssh root@198.145.115.XX

where XX is the last part of your Boxcar’s IP address. This will add the server’s host key to your known_hosts file and verify that your login is working ok.

Since you’re now logged in as root, this would also be a good time to install any gems that your application needs to work properly. Don’t worry about postgres/mysql/rails as Boxcar Conductor will take care of those for you during the deployment.

Step 2: Install the boxcar-conductor plugin

From the root directory of your Rails application (on your development machine) run:

script/plugin install git://github.com/planetargon/boxcar-conductor.git

to install the boxcar-conductor plugin. Note that the installer will attempt to copy an example deploy.rb and Capfile into your project. If these files already exist they will not be replaced. However, it is very important that your deploy.rb include all of the necessary sections from the example file. We suggest that you move Capfile and deploy.rb out of the way prior to installing boxcar-conductor to avoid any problems.

Once it’s installed you’ll need to edit the config/deploy.rb file to suit your settings. You’ll want to make sure you modify the following settings to what you need:

1. application_name—This is the name of your application (no spaces)
2. boxcar_server—This is the IP or FQDN of your Boxcar (starts with 198.145.115)
3. boxcar_username—The user you will use to deploy on the Boxcar. This user will be created for you when you deploy.
4. scm—This is the type of scm you’re using. Common options are “subversion”, “git” and “cvs”
5. repository—The path to your repository in the format that your scm expects it
6. ssh_options[:forward_agent]—Only set this to true if you are using an SSH key to connect to your Boxcar. If you’re using a password this won’t work properly.

Step 3: Configure your Boxcar

You’re now ready to run cap boxcar:config -q to deploy the configuration to your Boxcar. The first choice you’ll need to make is whether to use a quick or custom setup. The only difference between the two is whether you’re asked a bunch of mundane questions about your database setup. We recommend that you use the quick setup unless you really need to customize your deployment.

Note: If you are not using an SSH key to access your account, you will be prompted a few times for your password. The first time you are asked for a password it will be for root. After your deployment user is created, you will be asked for the deployment user password (to connect as the deployment user), and then one more time for the root password. This is why we recommend that you use public key authentication. :)

When you are asked for your database user, be sure to use the same name as your deployment user to avoid some potential authentication problems. (This is the default.)

After you answer a few questions, boxcar-conductor will begin the server setup for you, including installing your database, configuring your webserver, etc. Note that this can take a few minutes, so don’t be alarmed if it appears to just be sitting there.

Once the install is done, you will be asked if you’re ready to start the deployment. If your code is:

• hosted on github OR
• you’re doing a copy/export deployment from your local machine OR
• your SCM is being accessed via a method other than SSH (e.g. HTTP)

you can skip ahead to step 4. Otherwise, go down to 3a.

Step 3a: Update your deployment user’s known_hosts

Due to SSH’s paranoid security settings, you will need to manually add the host key for your repository to your deployment user. Just connect to your Boxcar as your deployment user (not as root), and run ssh your.deployment.url. You will be prompted to save the host key for the server. Type yes, hit enter, and then close the connection. (You don’t need to log in, only to have the host key saved.)

Step 4: Perform a cold deployment

If you’ve followed all of the directions to this point, your Boxcar should be ready to receive a deployed application. So answer “y” to the ready to deploy question and sit back.

If everything has gone well your application should now be accessible from the outside world! Congratulations, you’re done!

Updating your application

When it’s time to update your running Rails application, you just need to deploy it again by running the following command.

$ cap deploy

This will update your application from the subversion repository and restart the web server.