Web Application Deployment Using Webistrano and Capistrano

One of the 12 steps to better code, according to Joel Spolsky’s blog is one-click deployment. I’ve worked in places where the deployment process contained about 20 steps and involved a lot of copy-pasting of the paths and environment variables. It was obviously prone to errors, and very stressful for the developers involved. God forbid your wiki database crashed, and you lost all the steps!

One click deployment means faster, less buggy deployment. No more wondering, which environment you’re in at the moment, and if you just run that migration script on staging or production. You can even ask your Jimmy to deploy the lovely application for you.

There are quite a few tools that can help you deploy your applications:

• Ant/Phing
• Bash scripts
• Jenkins
• Aegir

Today, however I will focus on the mix of Capistrano / Webistrano.

Both of the packages are ruby on rails based, and can be easily installed using gems.

Capistrano is an open source tool that allows to run scripts on multiple servers. Capistrano automates the process of making new versions of an application as well as supporting tasks such as updating databases, rsyncing media assets etc.

Webistrano is a RoR open source UI for managing Capistrano deployments. It provides a descriptive interface for your projects and stages, and easy way to add environment specific settings.

Installation

Installing Capistrano is quick and easy as long as you have gems and ruby installed:

$ gem install capistrano

With capistrano installed, let’s move on with Webistrano installation. I want my install to be visible externally on http://webistrano.server.com. For this, I’m going to use Phusion Passanger. For now I’m going to install Webistrano straight in my httpdocs

$ cd /var/www/vhosts/webistrano.server.com/httpdocs
git clone git://github.com/peritor/webistrano.git .

Webistrano uses mysql to store the information about your project, stages and deployments, so let’s log in and set it up:

$ mysql
mysql> CREATE DATABASE `webistrano`;
mysql> CREATE USER 'webistrano'@'localhost' IDENTIFIED BY 'password';
mysql> GRANT ALL PRIVILEGES ON `webistrano`.* TO 'webistrano'@'localhost' WITH GRANT OPTION;

Now we need to configure it before we build it with rake. Two files that we need to copy: database (database.yml), and general, webistrano config file (webistrano_config.rb).

$ cp config/webistrano_config.rb.sample config/webistrano_config.rb
cp config/database.yml.sample config/database.yml

Now edit the file with your mysql details and other options you want to set.

And the last, but not least, before we start the build. Webistrano creates all the stylesheets on the first run, so the public folder has to have writeable permissions:

$ chmod -R 755 public

That’s it for the basic set up. What’s left is building webistrano. We’re going to need bundler to install it. If you don’t have bundler yet, use gem to install it:

$ gem install bundler

Now run rake to build webistrano:

$ RAILS_ENV=production rake db:migrate

If like me, you get the following error bundler (~> 1.0.10) ruby, otherwise move to the next step (bundle install)

rake aborted!
Bundler could not find compatible versions for gem "bundler":
In Gemfile:
bundler (~> 1.0.10) ruby
Current Bundler version:
bundler (1.2.1)[/code]

You will have to install an older version of the bundler. Gems allows you to keep different versions of the same package so this won't clash with your other ruby applications:

$ gem install bundler --version=1.0.10

If this was successful, or you haven't had any issues with your bundler, simply run bundle install

$ bundle install
Fetching source index for http://rubygems.org/
Installing rake (0.9.2.2)
Installing activesupport (2.3.11)
Installing rack (1.1.3)
Installing actionpack (2.3.11)
Installing actionmailer (2.3.11)
Installing activerecord (2.3.11)
Installing activeresource (2.3.11)
Using bundler (1.0.10)
Installing highline (1.6.15)
Installing jruby-pageant (1.1.1)
Installing net-ssh (2.6.0)
Installing net-scp (1.0.4)
Installing net-sftp (2.0.5)
Installing net-ssh-gateway (1.1.0)
Installing capistrano (2.6.0)
Installing erubis (2.7.0)
Installing exception_notification (2.3.3.0)
Installing mocha (0.9.8)
Installing mysql (2.8.1) with native extensions
Installing open4 (0.9.3)
Installing rails (2.3.11)
Installing syntax (1.0.0)
Your bundle is complete! It was installed into ./vendor/bundler

You need to build with rake again

$ RAILS_ENV=production rake db:migrate
WARNING: 'require 'rake/rdoctask'' is deprecated. Please use 'require 'rdoc/task' (in RDoc 2.4.2+)' instead.
at /var/www/vhosts/webistrano.server.com/httpdocs/vendor/bundler/ruby/1.8/gems/rake-0.9.2.2/lib/rake/rdoctask.rb
rake aborted!
no such file to load -- /var/www/vhosts/webistrano.server.com/httpdocs/config/webistrano_config
Tasks: TOP => db:migrate => environment
(See full trace by running task with --trace)

If you get this error find out what rake gems you've got installed by running gem list

$ gem list
=> rake

You'll have to specify the version of rake manually in your gem file:

$ vim Gemfile
gem rake, '0.8.7'

You will have to run bundle install again. We'll start from unlocking the version of rake that bundle currently has set to use, by updating bundle:

$ bundle update rake

Now install the correct bundle

$ bundle install

and run rake using bundle exec

$ bundle exec rake db:migrate --trace RAILS_ENV=production

Hurrah! You have successfully installed Webistrano!

Running Webistrano

** EDIT **

IN my original post I've been advising to use Phusion Passenger for Apache to run websitrano, but since it occurred it only causes trouble with permissions during deployment. Phusion Passenger should run as the user that has the ownership over conf/environment.rb which in my case was webistrano. All seemed ok, and logging the id of my user running Webistrano was pointing to the correct one, but it seems that there was some sort of conflict and the process was actually running as nobody. You can find more about the issue on stack overflow

With this in mind, I would recommend using mongrel instead.

$ sudo gem install mongrel
$ su - webistrano
$ cd /var/www/vhosts/webistrano.server.com/httpdocs
$ mongrel_rails start -e production -d -p 3000

Now go to http://webistrano.server.com:3000 and you should be able to see the login screen

login: admin 
password: admin

Success! You can now see the main Webistrano screen.

If this has wet your apetite, please read my next post about deploying PHP applications with Webistrano. Also, feel free to leave your comments below. I hope you found this post useful.