For the Rails applications we’re building at work, as well as all the
standard continuous integration features, we also automatically deploy
our applications. That is, every time we submit code a central server
is automatically updated with a new release. Before running tests.
We’re pretty happy with this set up. It’s already found a couple of
bugs in some plugins we’re using. More on that in an upcoming
post. Here’s how we made our automatic deployment work. We’re using
Capistrano for our deployment scripts, we’re deploying to Phusion
Passenger running under Apache on FreeBSD and our continuous
integration server runs an Ant script.
These instructions describe how to set up a Apache 2.2 web server with
Phusion Passenger on FreeBSD; the Ant script to automatically deploy
and how to configure a Rails app to be deployed like this.
This will give you two new environments for your apps: DEVTEST and
UAT. UAT is a user acceptance testing environment, our system testers
and analysts use and own this environment. We don’t automatically
deploy to here, we release to here. DEVTEST is the environment we
automatically deploy to.
Setting up Your Server
Installing Phusion Passenger
Installing Phusion Passenger on a FreeBSD server is no different to
installing anywhere else:
$ sudo gem install passenger
$ sudo passenger-install-apache2-module
Configuring Apache
At the end of the second step, the installer tells you to add some
config to the end of your Apache config. On FreeBSD, edit this with:
$ sudoedit /usr/local/etc/apache22/httpd.conf
And then add the following at the end:
LoadModule passenger_module /usr/local/lib/ruby/gems/1.8/gems/passenger-2.0.3/ext/apache2/mod_passenger.so
PassengerRoot /usr/local/lib/ruby/gems/1.8/gems/passenger-2.0.3
PassengerRuby /usr/local/bin/ruby18
NameVirtualHost *:80
<VirtualHost *:80>
ServerName devtest.example.com
ServerAlias devtest
DocumentRoot /usr/local/www/rails/devtest
<Directory "/usr/local/www/rails/devtest">
Options FollowSymLinks
AllowOverride None
Order allow,deny
Allow from all
</Directory>
RailsEnv "devtest"
</VirtualHost>
<VirtualHost *:80>
ServerName uat.example.com
ServerAlias uat
DocumentRoot /usr/local/www/rails/uat
<Directory "/usr/local/www/rails/uat">
Options FollowSymLinks
AllowOverride None
Order allow,deny
Allow from all
</Directory>
RailsEnv "uat"
</VirtualHost>
Unless you want to use two different servers for the two environments,
you’ll need to use named virtual hosts, and ask your friendly
administrator to add CNAME records to your DNS server pointing devtest
and uat at the same physical server. They’ll know what you mean.
Create a Local User
You’ll need a local user on your server. This is the user that will
run the automatic deployments.
$ sudo adduser
Username: deploy-robot
Full name: Deployment Robot
Uid (Leave empty for default):
Login group [deploy-robot]:
Login group is deploy-robot. Invite deploy-robot into other groups? []: www
Login class [default]:
Shell (sh csh tcsh zsh nologin) [sh]:
Home directory [/home/deploy-robot]:
Use password-based authentication? [yes]:
Use an empty password? (yes/no) [no]:
Use a random password? (yes/no) [no]:
Enter password:
Enter password again:
Lock out the account after creation? [no]:
Username : deploy-robot
Password : ****
Full Name : Deployment Robot
Uid : 1001
Class :
Groups :
Home : /home/deploy-robot
Shell : /usr/local/bin/sh
Locked : no
OK? (yes/no): yes
adduser: INFO: Successfully added (deploy-robot) to the user database.
Add another user? (yes/no): no
Goodbye!
Deployment Directories
Set up the directories to hold your applications.
$ sudo mkdir -p /usr/local/www/rails/devtest
$ sudo mkdir -p /usr/local/www/rails/uat
These are the web roots for each of the environments, but applications
will not be deployed here. Instead, symlinks will be created from here
to where the applications are actually deployed.
$ sudo mkdir -p /usr/local/app/rails/devtest
$ sudo mkdir -p /usr/local/app/rails/uat
These last two directories, and everything under them should be owned
by the deployment user you created above.
$ sudo chown -R deploy-robot:www devtest uat
Gems
Finally, there are some gems you’ll need installed on the target
deployment server. Some of these depend on FreeBSD ports.
$ cd /usr/ports/comms/ruby-termios
$ sudo make install clean
And then just a couple of gems.
$ sudo gem install termios
$ sudo gem install capistrano
And that’s it for initial server configuration. There will be some
more configuration when first deploying an application.
Preparing Your Application
Capistrano Config
Capify your application:
$ cd app
$ capify .
Edit your capistrano rules in deploy.rb. You’ll want them to look
something like the following. These rules use no source control
system to get the code. Our continuous integration server takes care
of checking out the code, so it’s easier to deploy from the local code
copy. And, this way we can be sure each deployment only contains one
changelist.
# Overall config
set :use_sudo, false
# Application config
set :application, "app-name"
set :default_env, "production"
set :rails_env, ENV['RAILS_ENV'] || default_env
# Deployment source and strategy
set :deploy_to, "/usr/local/app/rails/#{rails_env}/#{application}"
set :deploy_via, :copy
set :scm, :none
set :repository, "."
# Target servers
set :default_server, "localhost"
set :dest_server, ENV['SERVER'] || default_server
role :app, dest_server
role :web, dest_server
role :db, dest_server, :primary => true
# Phusion Passenger specific restart task
namespace :deploy do
desc "Restart Application"
task :restart, :roles => :app do
run "touch #{current_path}/tmp/restart.txt"
end
end
Environment Configuration
Set up the two new environments for your application.
$ cp config/environments/production.rb config/environments/devtest.rb
$ cp config/environments/production.rb config/environments/uat.rb
Somewhere inside both those files you’ll need to set the
RAILS_RELATIVE_URL_ROOT as the application will be running at a
sub-URI on your server and Rails needs to know that. Something like:
ENV['RAILS_RELATIVE_URL_ROOT'] = "/app-name"
The two new environments will also need to be described in your
database.yml file. This of course depends on your specific database
server setup, so I’ll leave that bit to you.
Server-side Application Setup
Apache needs to know about the applications, and there needs to be
symlinks from the web root to the application deployment folder. This
setup only needs to be done once for each application.
To add the application to Apache, edit
/usr/local/etc/apache22/httpd.conf again, and in the VirtualHost
section for the devtest environment, add a line like the following:
RailsBaseURI /app-name
Now, set up the symlink:
$ ln -s /usr/local/app/rails/devtest/app-name/current/public /usr/local/www/rails/devtest/app-name
And you’re done with the application configuration.
Ant Deployment Scripts
Our company has an in-house continuous integration server. We’d be too
embarrassed at cocktail parties if we didn’t have our own. Yes, yes, I
know this is completely ridiculous. And to make it even worse, it only
runs Ant scripts. Sigh. Anyway, here’s how you make Ant automatically
deploy an application to devtest.
In a file called definitions.xml:
<project name="definitions_rake">
<macrodef name="rake">
<attribute name="app" />
<attribute name="target" />
<element name="variables" optional="true" />
<sequential>
<exec executable="rake" dir="@{app}" failonerror="true">
<arg value="@{target}" />
<variables />
</exec>
</sequential>
</macrodef>
<macrodef name="capistrano">
<attribute name="app" />
<attribute name="environment" />
<attribute name="task" />
<sequential>
<exec executable="cap" dir="@{app}" failonerror="true">
<env key="RAILS_ENV" value="@{environment}" />
<env key="SERVER" value="${project.server}" />
<arg value="@{task}" />
<arg value="-s" />
<arg value="user=${project.user}" />
<arg value="-s" />
<arg value="password=${project.password}" />
</exec>
</sequential>
</macrodef>
<macrodef name="deploy">
<attribute name="app" />
<attribute name="environment" />
<sequential>
<capistrano app="@{app}" environment="@{environment}" task="deploy:setup" />
<capistrano app="@{app}" environment="@{environment}" task="deploy:migrations" />
</sequential>
</macrodef>
<macrodef name="test">
<attribute name="app" />
<sequential>
<rake app="@{app}" target="db:migrate" />
<rake app="@{app}" target="test" />
<rake app="@{app}" target="spec" />
</sequential>
</macrodef>
</project>
Ant macros, while quite insane, are generally a better way to define
new tasks than the complete insanity of trying to write a whole Ant
plugin in Java. These macros define low-level tasks to run rake and
capistrano tasks, and then use these to build up higher level tasks
like test and deploy. All these tasks assume that Ant has been run
from the directory immediately above your Rails app directory.
In a file called project.properties, set your server, user name and
password. Having the password here is unfortunate, but it is a local
account, with limited privileges on an internal server. Your call.
user=deploy-robot
password=deploy-robot-password
server=deployment-server
In a file called build.xml:
<project name="aegean" default="build">
<import file="./definitions.xml" />
<property file="project.properties" prefix="project" />
<!-- Sample application.
To add a new application:
1. Copy the following targets.
2. Replace 'depot' with your Rails app name.
3. Add the 'app name' target as a dependency of the target 'build'.
<target name="depot.deploy.devtest">
<deploy app="depot" environment="devtest" />
</target>
<target name="depot.test">
<test app="depot" />
</target>
<target name="depot" depends="depot.deploy.devtest, depot.test" />
-->
<target name="example.deploy.devtest">
<deploy app="example" environment="devtest" />
</target>
<target name="example.test">
<test app="example" />
</target>
<target name="example" depends="example.deploy.devtest, example.test" />
<target name="build" depends="example" />
</project>
The large comment block is just helpful for other developers trying to
add another application. From here, to try this out:
$ ant
It should run the deployment, and then run the test suites. If that works as you expect, then just configure your continuous integration server to run Ant over that file on every submit.
Hopefully this is of use to someone. Though this is how our
environment is configured, I have written this all from memory, so I
might have missed a critical step somewhere. Please let me know if
there’s anything that needs to be changed.