How to install Redmine with nginx and Mongrel Cluster on Gentoo Linux?

Recently I’ve migrated GOYELLO‘s Redmine installation to Gentoo Linux. I’ve used nginx as a load balancer and proxy to Mongrel Cluster. Read on to learn more about the installation process of this flexible and scalable setup.

Gentoo

I’ve chosen Gentoo Linux because it is a stable and lightweight operating system. Gentoo installation process is not in the scope of this post. To learn more about it read the official documentation. The tips you will find in here might be, however, useful for other Linux distributions as well. The main and the only difference should be software installation commands (which are distro specific).

Ruby On Rails

Redmine is built on top of Ruby On Rails framework (ROR). The required ROR and Ruby versions depend on Redmine release. My installation works with rails 2.2.3. I needed to force it as currently Gentoo would install it in 2.3.5 version:

USE="mysql fastcgi" emerge -av '=rails-2.2.3'

In case you don’t need any specific release just use the latest:

USE="mysql fastcgi" emerge -av rails

USE environment variable declared before the command tells the compiler to include support for MySQL and fastcgi.

MySQL

MySQL should be already installed as a dependency for rails. Still it requires configuration before we can start it:

emerge --config mysql
/etc/init.d/mysql start

You should be asked for the root user password. It’s a good idea to set it. Also, for security reasons, it is advised to use a dedicated user for Redmine connections. Run MySQL console with mysql -p and invoke following SQL queries to create the user and give him permissions for local host connections:

CREATE USER redmine identified by 'my$ecret';
GRANT ALL ON *.* TO 'redmine'@'localhost' IDENTIFIED BY 'my$ecret';

Redmine

In my case I already had Redmine installation running on a different machine. What I really did here was check out the files from repository and copy the database. I put the  files into /var/www/redmine.goyello.com. If you’re starting your installation from scratch official installation guide is a decent reference.

Before you proceed to the next steps it is a good idea to verify if Redmine is correctly configured and is able to run. Following command should be invoked in the Redmine’s installation directory.

ruby script/server -e production --port=3000

Press ctrl+c to stop WEBrick once you’ve tested Redmine in your browser.

nginx

Nginx installation is really simple:

USE="fastcgi" emerge -av nginx

Configuration files are really straight forward and self explanatory. I’ve put my Redmine’s configuration into /etc/nginx/sites/redmine.conf:

upstream mongrel {
  server 127.0.0.1:9000;
  server 127.0.0.1:9001;
  server 127.0.0.1:9002;
}

server {
  listen 80;
  server_name redmine.goyello.com;
  root /var/www/redmine.goyello.com/public;
  access_log /var/www/redmine.goyello.com/log/redmine.access_log main;
  error_log /var/www/redmine.goyello.com/log/redmine.error_log info;

  location / {
    proxy_set_header  X-Real-IP  $remote_addr;
    proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header  Host $http_host;
    proxy_redirect off;
    proxy_read_timeout 300;

    if (-f $request_filename/index.html) {
      rewrite (.*) $1/index.html break;
    }

    if (-f $request_filename.html) {
      rewrite (.*) $1.html break;
    }

    if (-f $request_filename.txt) {
      rewrite (.*) $1.txt break;
    }

    proxy_pass http://mongrel/;
  }
}

This way nginx will proxy requests to three mongrel servers. The best thing is that load balancing works out of the box. We could define more mongrel servers in the upstream section. It really depends on our needs. To make it work I included all configuration files from /etc/nginx/sites directory in the main configuration file (/etc/nginx/nginx.conf):

http {
  include /etc/nginx/sites/*.conf;
}

Nginx is ready to start now:

/etc/init.d/nginx start

Mongrel Cluster

Mongrel Cluster makes it easy to deploy web applications on the cluster of mongrel servers. In Gentoo it is not a stable package so we need to unmask it:

mkdir /etc/portage
echo "=www-servers/mongrel_cluster-1.0.5 ~x86" >> /etc/portage/package.keywords

Unstable package in Gentoo doesn’t mean that software is unstable. It just means that the package itself was not fully tested and approved in the distribution. Again installation itself is simple:

emerge -av mongrel_cluster

Next we need to put configuration directories and init script in place:

mkdir /etc/mongrel_cluster
ln -s /etc/mongrel_cluster/redmine.yml /var/www/redmine.goyello.com/config/mongrel_cluster.yml
cp /usr/lib/ruby/gems/1.8/gems/mongrel_cluster-1.0.5/resources/mongrel_cluster /etc/init.d
chmod +x /etc/init.d/mongrel_cluster

Configuration is made with a simple command:

mongrel_rails cluster::configure -e production -p 9000 -N 3 \
  -c /var/www/redmine.goyello.com/ --user nginx --group nginx \
  -C /etc/mongrel_cluster/redmine.yml

We chose to run three mongrel instances. The first one will listen on port 9000 and the others will get next ports available. Note that we used these ports in upstream section of nginx configuration.

Last thing we need to do is to set right permissions for Redmine files. Both nginx and mongrel will run as a nginx user:

chown -R nginx:nginx /var/www/redmine.goyello.com/
chmod -R 775 /var/www/redmine.goyello.com/

Now we can start our mongrel servers with:

/etc/init.d/mongrel_cluster start

Finalising the setup

We should already be able to see Redmine in a browser and we are almost done with the installation. The only thing left to do is to include all the services in the boot process.

update-rc add mysql default
update-rc add nginx default
update-rc add mongrel_cluster default