A place for opinions and notes of a valibuk.

Rails, Capistrano, Mongrel and Apache (with SSL) on Gentoo

Tagged with: — ondrej at 2:25 am on Monday, January 8, 2007

Ruby on Rails
There is a happy occasion in the development of an application — deployment. Users will use it, you will receive (hopefully) some money, there will be some bugs.. well, maybe not so happy occasion.. ;>
In most situations you will have to repeat a deployment process several times (bug fixes, new features, etc.). Maybe the process is not very complicated, but an automation will minimise possible mistakes such as typos or omitted commands.
Fortunately, there is a nice tool for Ruby on Rails applications — Capistrano.

Larry the CowNow we know about a tool to automate the deployment of an application, but we need to deploy our application to a production environment — I decided for the combination of Mongrel and Apache.

…and everything runs on Gentoo :)

Let’s start — here is my short howto:


Let’s define CLIENT as a computer where you are developing an application, SERVER as a computer where you are going to deploy it and APP as the name of your application.
I assume that Gentoo is installed on both computers.

I decided to create a special user APP for the application on the server (if you do not like it, then all paths /home/APP replace with your favourite path ;).

I prefer the PostgreSQL database.

A short remark for copying text — if you would like to copy a text without any line numbers (they are fine for reading, but not for using on a command line or in a text file) click on the [Show Plain Code] link for each block of code or configuration file to display an unformatted text.

I. Client Software Installation

We will need to install Capistrano and Mongrel:

  1. emerge ruby-termios capistrano

bacause there is not ebuild for Mongrel, you have to install it with gem:


(The -y option is a shortcut to the --include-dependencies option.)

II. Server Software Installation

Let’s install necessary software:


We will need Apache 2.2 (because the mod_proxy_balancer) that is masked in the portage (7. January 2007), so it is necessary to unmask it:
add the following lines to the /etc/portage/package.unmask file:

  1. net-www/apache
  2. dev-libs/apr
  3. dev-libs/apr-util

to the /etc/portage/package.keywords file (thanks to Steve for his comment how to improve this):

  1. ~net-www/apache-2.2.3
  2. ~dev-libs/apr-1.2.7
  3. ~dev-libs/apr-util-1.2.7

and install it:

  1. emerge apache

If you plan to support SSL (for a secure communication between a client and the server), do not forget to add the ssl use flag for Apache — add the following line to the /etc/portage/package.use file:

  1. net-www/apache ssl

III. Server Side Configuration

Let’s create a special user for the application (not necessary):

  1. useradd -d /home/APP -m APP
  2. passwd APP

Open the /etc/sudoers file and add the following line:

  1. APP    ALL=(ALL) ALL

The main reason for creating a special user was a fact that the sudo command has to be available for a user. Frankly, I do not like the sudo command (sorry, Ubuntu guys). With su - it is clear when I have root privileges and when not (on Ubuntu I usually type sudo sh :).

I also created a new database user APP:

  1. su –
  2. su – postgres
  3. createuser APP

and a new production database:

  1. createdb -E utf-8 APP_production

IV. Client Side Configuration

Go to the application directory and create a configuration for Mongrel:


it will create the config/mongrel_cluster.yml file; basically you do not need to edit it.

Then create a configuration for Capistrano (do not forget that APP is the name of your application):

  1. cap –apply-to . APP

and in this case we need to modify the generated file config/deploy.rb — I added or changed the following lines:

  1. span style=”color:#008000; font-style:italic;”>#you set the APP name with the cap command
  2. "APP"
  3. #a path to your repository
  4. "svn+ssh://USERNAME@SVN_SERVER/projects/#{application}/trunk"
  6. role :web, "SERVER""SERVER"
  7. role :db, "SERVER"#where to deploy (copy the files) on the server; I created a special user APP for the application (if you do not like it, replace the /home/#{application} part with your path
  8. "/home/#{application}/production/#{application}"
  9. set :mongrel_conf, "#{current_path}/config/mongrel_cluster.yml"
  10. #if the server login name is different to the development computer login name; in my case the user name is the APP name
  11. set :user, "APP"

It is also necessary to update the config/database.yml file:

  1. #no changes needed, just to show the development configuration
  2. #I changed the username to the database user name on the server

Do not forget to add all new files and commit all changes (because Capistrano uses files in your repository).

V. Deployment

Create the basic structure on the server (files from the repository is not used in this step):


If there is something wrong: check the config/deploy.rb file; try to log to the server manually e.g. ssh APP@SERVER or ssh APP@SERVER -v -v -v; did you add and commit the config/deploy.rb file?

Let Capistrano do the magic :)

  1. rake remote:cold_deploy

If there is something wrong: check the config/deploy.rb file; try to check out the repository manually on the server.

To check if everything went fine, access the http://SERVER:8000 link or the http://localhost:8000 link on the server. If you have a firewall, probably only the second option will work — you can use the console browser lynx or to be more professional ;) wget http://localhost:8000.

Anytime you can delete the /home/APP/production directory on the server and start from scratch. All files are safely stored in your repository. (Except the data in the database on the server.)

If you use migrations to create databases and to insert initial data (of course that you are! :), call the following command to run migrations on the server:

  1. rake remote:migrate

For any next deployments use the following command:

  1. rake remote:deploy

VI. Apache Configuration

Log to the server as root (do you remember? su - :) and add the -D PROXY option to the /etc/conf.d/apache2 file. Because I have Apache only for one application, my configuration looks like:


i.e. I removed the -D DEFAULT_VHOST and -D SSL_DEFAULT_VHOST options.

For the new application we will create a new virtual host — create a new /etc/apache2/vhosts.d/01_APP_vhost.conf file with the following content[RoRBook] (do not forget that APP is the application name):

Apache [Show Plain Code]:
  1. span style=”color: #7f007f;”>"/home/APP/production/APP/current/public"# Check for  maintenance file and redirect all requests
  2. # Rewrite index to check for static
  3. # Rewrite to check for Rails cached page
  4. # Redirect all non-static requests to cluster

Restart the Apache web server:


and test the http://SERVER link (or http://localhost on the server) — your application should appear :)

Of course, do not forget to add the Apache service to start when the server starts:

  1. rc-update add apache2 default

To start the Mongrel instance I added the following line to the /etc/conf.d/local.start file:


You can stop server with the cluster::stop action and start with the cluster::start action.

VII. Apache SSL Configuration

As a bonus, here are instructions how to setup the SSL support. I wanted to have only one application that has to be accessible only via HTTPS, i.e. if a user uses insecure HTTP, (s)he will be automatically redirected to secure HTTPS.

Change the /etc/apache2/vhosts.d/01_APP_vhost.conf file:

Apache [Show Plain Code]:
  1. span style=”color: #7f007f;”>"/home/APP/production/APP/current/public"‘https’# Check for  maintenance file and redirect all requests
  2. # Rewrite index to check for static
  3. # Rewrite to check for Rails cached page
  4. # Redirect all non-static requests to cluster
  5. # Redirects only the URL http://SERVER to https://SERVER, but not http://SERVER/anything
  6.         #Redirect permanent / https://SERVER
  8.         # More general redirect, it redirect all URLs http://SERVER/anything to https://SERVER/anything

It is necessary to create a certificate file and a certificate key files[ApacheDoc]:

  1. #key file, do not forget the pass-phrase
  2. openssl genrsa -des3 -out APP.key 1024
  3. #certificate file; for the "Common Name" (CN) type the SERVER name or the SERVER IP address
  4. openssl req -new -x509 -nodes -sha1 -days 365 -key APP.key -out APP.crt
  5. #decrypted key file; not very secure

and copy the last two created files to the /etc/apache2/ssl/ directory.

I use the decrypted key file, because the Apache web server asks for the pass-phrase when it starts with an encrypted key file.

Hopefully I helped you to configure your production environment. Btw. this is my first production installation :), so if you have better experiences, please, you are welcome to write a comment…

[RoRBook] Agile Web Development with Rails, 2nd edition

These icons link to social bookmarking sites where readers can share and discover new web pages.
  • DZone
  • Digg
  • Reddit
  • Technorati
  • Furl
  • NewsVine
  • Slashdot
  • Ma.gnolia
  • StumbleUpon



Pingback by Planeta Gentoo » » Rails, Capistrano, Mongrel and Apache (with SSL) on Gentoo

January 12, 2007 @ 7:53 am

[…] Original post by […]


Comment by Steve

January 13, 2007 @ 3:37 am

A couple notes…

it should be --include_dependencies (double-dash)

your package.keywords file should have…

~net-www/apache-2.2.3 ~x86
~dev-libs/apr-1.2.7 ~x86
~dev-libs/apr-util-1.2.7 ~x86

I’ll be doing the Apache stuff later, this is as far as I got tonight.

Thanks for the guide :)

Oh – I totally disagree about sudo, but I always have others helping with server administration… ymmv :)


Comment by ondrej

January 13, 2007 @ 4:32 pm

Hi Steve,

Thanks for your comment :)

i) The double-dash was there, unfortunately my code highlighter changed it to a simple dash. I will check it.

The [Show Plain Code] link shows unformatted text — you would see a double-dash there.
Anyway, I changed it to the equivalent option -y; to not to confuse others.

I also added a comment to the post (in the Introduction part) to click on the above-mentioned link to display an unformatted text.

ii) You do not have to write the ~x86 flag in the package.keywords file. It is there by default; it is enough to write a package name there.

I modified the package.keywords file content — it is better when readers will install only the needed version 2.2.3 — and not any newer version.

iii) The sudo issue.. It is only my (bad?) habit :)

Thanks for your help!

Have a nice day :)

Comment by jesper

March 1, 2007 @ 12:20 pm

hey, thanks for a great article

but mongrel cluster:configure should be mongrel cluster::configure

Comment by ondrej

March 1, 2007 @ 12:29 pm

you are welcome :)
and thanks for your correction.

Trackback by Juan C. Mendez's pages

March 4, 2007 @ 4:14 am

Long time, no posts…

I’ve been actively setting up the site for the new service company I’m starting:, so posting here on my personal site has been scarce.
During the setup of the fulfillment portion of the new site, I found good instructions on v…

Pingback by » Ruby on Rails, Capistrano, Mongrel and nginx on Gentoo

August 30, 2007 @ 1:25 am

[…] few months ago I wrote quite popular :) manual how to install and use RoR, Capistrano and Mongrel with Apache on Gentoo. Things changed a little as the time goes and after some experiences with the nginx server on a […]

Comment by Dmitry

October 30, 2007 @ 7:28 pm

Hi to all,

I changed all by instruction application is works, but SVN at my machine doesn’t work after change.

Do you have any ideas?

Comment by ondrej

November 11, 2007 @ 2:30 pm

Hello Dmitry,

Sorry, I do not understand what exactly does not work on your machine. Did SVN as an application stop working? Or you cannot access your SVN repository from your machine anymore?

Try to check out your application manually on the server. Then check the SVN repository settings in the Capistrano settings (conf/deploy.rb).

Comment by ondrej

November 11, 2007 @ 2:32 pm

I updated the Apache SSL configuration. Now it redirects all http://server/anything requests to https://server/anything.

The previous configuration (it is commented out there) redirected only http://server, other URLs were redirected not correctly.

Pingback by RAILroading » Blog Archive » links for 2008-01-19

January 19, 2008 @ 5:07 am

[…] » Rails, Capistrano, Mongrel and Apache (with SSL) on Gentoo (tags: apache mongrel rubyonrails ssl) […]

RSS feed for comments on this post. TrackBack URI

Leave a comment

XHTML: You can use these tags: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

Comment Preview

commercial break :)

Make an account on -- a really good hosting where you have your own virtual machine. I installed Gentoo there = I like it very much ;)