Deprec/Capistrano Rails installation and app deployment for Ubuntu

Updated instructions for deprec2 from Linux and from Windows

You can install more than one rails app on a single slice. See more_than_one_deprec_on_a_slice, or multiple_rails_apps_on_one_slice.

Capistrano and the Deprec add-ons are a great time saver for deployment and can greatly ease the initial install and config of a Rails+Apache+Mongrel+Mysql slice on Ubuntu. This is especially true for those somewhat new to command line administration of a Linux server. The purpose of this guide is to walk through the steps and explain what is happening in the background so that hopefully a total newbie can be up and going with Deprec in no-time flat.

As you will see shortly, the total time from freshly purchased slice to deployed and running rails app can literally be under 15 minutes. The trick is to have your local development environment set up properly and of course to know and use Deprec. It is worth the initial time it will take to learn and understand capistrano to have a reproduceable deployment.

For those of you who hate surprises, here is the last page of the novel first. Let’s assume that you have gone through the work to set up your local development environment. Here is how a new deployment of your rails app would look.

1. As a prerequisite, you already have Rails set up on your local machine
2. You install the Capistrano and Deprec on your local machine, explained further down this page
3. You create a brand new Ubuntu slice via the Slice Manager and get the IP and root password
4. Immediately log in to your slice and change the root password. This is the only thing you do on your slice. Everything else (all of the cap commands and editing deploy.conf) happens on your *local* machine, inside your Rails project directory.
5. Log out of your slice
6. On your local development environment you execute the following commands:

  cap setup_admin_account_as_root
  cap setup_ssh_keys
  cap install_rails_stack
  cap setup
  cap deploy_with_migrations
  cap restart_apache

And, thats it! Not only is rails now installed (ditto for Apache, Mongrel and Mysql), but so is your application and it is running.

As mentioned, the key is to have your development house in order. This includes installing capistrano and deprec, setting up source control, generating ssh keys, applying deprec to an application and editing the config to your tastes.

Of course a prerequisite to all this is that you need to have rails set up (and functional) on your development machine. Some of the problems that newcomers encounter trying to use deprec is that in fact their local rails setup is a bit out of whack. So if you can’t get past a step because of errors, check there first. Any number of things could be slightly askew, so to to keep this page uncluttered, we will keep a separate page to track some. One thing that is important enough to mention here is that the rails version that will be installed by deprec is currently 1.2.2. If your environment.rb in your project specifies an older version, mongrel will fail to start.

Also, lets for now keep a separate page for Windows aficionados who are dreaming of using deprec on windows. It is likely that at some point deprec won’t need work-arounds on Windows rails, but for now it does.

Ok, still with us? I guess that means you are using one of our preferred development platforms like OS X (or if you are super-cool Linux). In addition we can assume that you at least think your rails install is intact and correct. Great, let’s get to work.

As you are following along, keep common_deprec_setup_errors open - if you run in to a problem, it’s likely listed here.

Please take a look at http://deprec.rubyforge.org/, it contains the most updated readme on deprec.

Deprec and Cap are both under continuous development. Because of this, documentation and wiki’s will fall out of date rather quickly. This info is accurate as of 2-19-2007 and for Capistrano 1.4.0 and Deprec 1.2.3. So be warned not to try and compare to potentially out of date instructions.

 gem install capistrano -v 1.4.1 # installs older version so that these instructions will work (current Capistrano (= 2.0.0))
 gem install deprec
 echo "require 'deprec/recipes'" >> ~/.caprc

If things are correct you should be able get a list of known capistrano tasks:

 cap show_tasks

Verify that you see “deprec_setup” in the list. Next apply deprec to your application. All this really does is create a template “deploy.rb” for you. If you don’t have DNS setup for a domain, either stick an entry in /etc/hosts or use your slice IP in place of “www.projectname.com”

 cd /path/to/railsapp
 deprec --apply-to . --name projectname --domain projectname.com

Creating ssh keys for your development user and uploading the public key to your slice will allow deprec (and you) to access your slice over ssh without needing to enter a password. The key files are typically called “id_rsa” and “id_rsa.pub” and usually found in .ssh folder of your home directory. If you don’t have keys or would like to generate new ones-

 ssh-keygen -t rsa

You may use a passphrase if you would like. This passphrase is used to protect your private key on your local environment and will need to be entered to use the password-free authentication to the slice.

Once you’ve generated the keys, ssh into your slice, create a .ssh folder in the home directory of the root user, then create an ‘authorized_keys’ file, and paste the contents of your local ‘id_rsa.pub’ into it. After that, you should be able to ssh into your slice from your local machine without using a password.

These edits should flow top to bottom in the file.

add this line

  set :sudo, 'sudo -p Password:'

Do you have svn setup somehwere? Edit this line to point to your repo

  set :repository, "svn+ssh://#{user}@#{domain}#{deploy_to}/repos/trunk"

If your subversion username and password differ from deploy and deploy’s password, you can add the following two lines after set :repository:

  set :svn_username, "svnuser"
  set :svn_password, "secretpassword"

If you are using a different revision control system add this line (after the other role’s at the top) and Cap will set it up for you on the slice.

  role :scm, domain

see darcs manual about making repos public

  set :scm, 'darcs'
  set :repository http://domain/repos/club

install darcs on the server

  apt-get install darcs

Basically all of apache config is commented. I would recommend uncommenting the whole lot except for the apache_server_aliases and the ssl lines (assuming you don’t need ssl). Alter the apache_conf line to use the apache2 path as below. Alter the number of apache_proxy_servers, this is the number of mongrels you will be running. Lets pick 4 for this example. Here is the complete apache section. If you have other rails apps on this server, remember to pick a different range for :apache_proxy_port.

  # =============================================================================
  # APACHE OPTIONS
  # =============================================================================
  set :apache_server_name, domain
  #set :apache_server_aliases, %w{alias1 alias2} 
  #set :apache_default_vhost, true # force use of apache_default_vhost_config
  #set :apache_default_vhost_conf, "/etc/httpd/conf/default.conf"
  set :apache_conf, "/usr/local/apache2/conf/apps/#{application}.conf"
  set :apache_ctl, "/etc/init.d/httpd"
  set :apache_proxy_port, 8000
  set :apache_proxy_servers, 4
  set :apache_proxy_address, "127.0.0.1"
  # set :apache_ssl_enabled, false
  # set :apache_ssl_ip, "127.0.0.1"
  # set :apache_ssl_forward_all, false
  # set :apache_ssl_chainfile, false

You should also just uncomment most of the mongrel lines “as-is”. The only ones that you can leave commented are the mongrel_user and mongrel_group options. These are the system accounts that mongrel will run as if you want to alter that from the default.

  # =============================================================================
  # MONGREL OPTIONS
  # =============================================================================
  set :mongrel_servers, apache_proxy_servers
  set :mongrel_port, apache_proxy_port
  set :mongrel_address, apache_proxy_address
  set :mongrel_environment, "production"
  set :mongrel_config, "/etc/mongrel_cluster/#{application}.conf"
  # set :mongrel_user_prefix,  'mongrel_'
  # set :mongrel_user, mongrel_user_prefix + application
  # set :mongrel_group_prefix,  'app_'
  # set :mongrel_group, mongrel_group_prefix + application

Uncomment this line

  # XXX set :user, ENV['USER']

Edit it to hold the name of your remote deployment account on the slice. For our example we are going to use the name “deploy”, but it can be anything.

  set :user, 'deploy'

Uncomment this line and edit it to match the key you just created

  # ssh_options[:keys] = %w(/path/to/my/key /path/to/another/key)

Only list the path to “id_rsa”, it automatically appends the “.pub”.

  ssh_options[:keys] = %w(/Users/jason/.ssh/id_rsa)

In this step we are going to create a remote user and setup your ssh authentication keys. Start with this command:

  cap setup_admin_account_as_root

Cap will prompt you “Enter userid for new user:”
This is the user account that will be created on the slice. It does not need to match your development machine user. We will use “deploy”.

Cap will prompt for a password, this is the slice root password. Then it will prompt you to Enter and Retype a “new UNIX password:”, which will be the password you want to set for the “deploy” user we just created.

Next run and when it asks enter the password for the deploy user.

  cap setup_ssh_keys

Now you should be able to log in to your slice using the ssh keys. Try this out

  ssh deploy@yourip

If you used a passphrase for is_rsa, it will prompt you to enter, otherwise you should just get dumped right into your slice shell. From here on, the deploy user’s password should be the only one prompted for (that and the id_rsa passphrase if you used one).

EDIT: As of 3/12/2007 the url used to download Apache in this step is broken. You will need to patch it manually to do this step. See common_deprec_setup_errors

UPDATE: May 2007 - new release of Deprec, if you install / update Deprec to version 1.6.0 you don’t have to worry about patching Deprec for the Apache location.

If you’ve upgraded your slice to Ubuntu 7.04, you’ll need to manually uncomment out the universe repository lines in the file /etc/apt/sources.list

Here is the step where deprec really earns its keep. Ready, set, RAILS!

  cap install_rails_stack

After you realize how much work Mike just saved you, remember that you owe the man a tasty beverage if he ever ends up in your town. Amazingly this is the step with the most work being done and it requires the least interaction. Note that this step will typically take at least several minutes to execute.

If you install_rails_stack fails with the error configure: error: Cannot use an external APR-util with the bundled APR, check the common_deprec_setup_errors page, under the section ‘Apache fails to compile’.

If you have deprec 1.6.0 or later installed, you can install PHP at this point with a simple

  cap install_php

And that’s it.

Sidenote: If you’ve previously used deprec to set up your slice, but you’d like to add PHP support, upgrade your deprec gem on your local development machine:

  sudo gem install -y deprec

And then reinstall apache:

  cap install_apache

Then run:

  cap install_php

As of deprec 1.6.0, you can just use:

  cap setup

Earlier versions run

  cap deprec_setup

Towards the end, this task will ask you for a password. Read the prompt carefully: it is asking for the root database password, which is actually blank. Just hit enter.

If you are running the task a second time, for whatever reason, you will get an error message after putting in the password if the previous run has already set up the database for your app. You can safely ignore this provided the database was set up correctly during the initial run. Since this is the last part of the setup task, the fact that it errors out will not cause any further step to be missed.

This step is only if you do not have an existing svn repository to point to (i.e. you set up an :scm role above).

  cap setup_scm

This will create an svn repository on the slice and make an initial check in from your local directory. It will then check out a working copy to a new local directory. When the process is complete you will see something like:

  Your repository is: svn+ssh://deploy@www.domain.com/var/www/apps/testapp/repos/trunk
  Please change to your new working directory: ../testapp_machine

The initial rails directory for this example was “testapp”. That directory can be archived now and should no longer be used for development. Now, all changes will happen in “testapp_machine” so that they can be committed to the svn repository (feel free to rename back to testapp if you would like). Moving to the new directory and editing deploy.rb again, replace the svn config line.

  set :repository, "svn+ssh://#{user}@#{domain}#{deploy_to}/repos/trunk"

Set it to the url that setup_scm gave you

  svn+ssh://deploy@www.domain.com/var/www/apps/testapp/repos/trunk

The svn setup will use the “deploy” user and password.

This command will check out your application from the svn repository into a folder in “releases” and sym link the current version to a folder called “current”. It will also run db:migrate and start the mongrel cluster.

  cap deploy_with_migrations

After starting mongrel, all that is left to do is start up apache.

  cap restart_apache

NOTE: If you run cap deploy_with_migrations and capistrano seems to hang, and then a timeout occurs, check your svn repository url is using a domain name that the slice knows about. If it does not know about it, add it to /etc/hosts.

Your rails app is now deployed. What now? Let’s imagine that you find a bug and make a change in your local development tree that you are happy with. Here is how you move the change into production.

Commit your changes (make sure that you are in your rails development working directory (testapp_machine for our example).

  svn commit -m 'I fixed a bug!'

When you are ready to actually move the changes into production run start with:

  cap disable_web

This handle little command decouples your apache web front from your mongrel cluster, putting up a “maintenance” page. Now deploy the new version

  cap deploy_with_migrations

And finally take down your maintenance page

  cap enable_web

Many thanks to Mike and Craig for the work they’ve done with deprec and capistrano!

http://deprec.rubyforge.org/

Mike Bailey (deprec Author)
http://codemode.blogspot.com/

http://wiki.rubyonrails.org/rails/pages/Capistrano

Craig Ambrose (deprec testing and documentation and the guy who told us about it)
http://blog.craigambrose.com/

common deprec setup errors

using deprec on windows