Debian Squeeze, Redmine, Backlogs and Gitolite

Installing Redmine on a Debian Squeeze machine turned out to be bit challenging, especially for a person like me not closely associated with Ruby based development. The below blog post just explains what I did to get the nice setup of Redmine project management system along with Redmine-Backlogs plugin for managing agile, scrum tasks and sprint cycles. You may find it helpful to bring up a similar setup for your own consumption.

Redmine, nginx and passenger packages are custom built and are not installed from the official Debian repository. Please remember that you need to be a root/superuser in order to go further. Please assume that all the tasks have been performed as 'root' user unless explicitly mentioned. The dependency packages as mentioned below, are installed form the Debian repositories using the usual apt-get command. I choose /opt as the directory to install customized software. '$>' just indicates the command prompt in the terminal. Make sure your proxy settings are fine, if your machine is running behind a proxy.


Final, installed system will have the following:

• Web server: Nginx
• Project management system: Redmine (v2.0)
• Scrum or Agile plugin for Redmine: Redmine Backlogs (v0.9.26)
• Ruby on Rails interface to Nginx: Phusion Passenger
• Database used for Redmine: Postgresql (v8.4, installed from Debian repository)
• Source control system: Git with Gitolite installation for repository management (git and gitolite are installed from Debian repository itself)

Basic system setup:

• My /etc/apt/sources.list file contents, showing the Debian repositories which I use. Please verify whether you have
  
deb http://ftp.de.debian.org/debian/ squeeze main contrib non-free
deb-src http://ftp.de.debian.org/debian/ squeeze main contrib non-free

deb http://security.debian.org/ squeeze/updates main contrib non-free
deb-src http://security.debian.org/ squeeze/updates main contrib non-free

deb http://ftp.de.debian.org/debian/ squeeze-updates main contrib non-free
deb-src http://ftp.de.debian.org/debian/ squeeze-updates main contrib non-free

  
• Install some of the important, dependency packages such as, g++, libtool, intltool, autoconf, automake, make, subversion, git, gitolite and rubygems, which are used by gem and passenger tools to download, compile and install the packages.
• Install additional development dependency packages such as postgresql, postgresql-contrib, libpq-dev, libxslt1-dev, libxml2-dev, libssl-dev as required by nokogiri gem and redmine. Install libcurl4-openssl-dev as required by passenger-install-nginx-module while compiling nginx.

Optional, proxy configuration if you are behind any proxy:

• Install the socat package using apt-get.
• Copy the following shell script into a file named /usr/local/bin/gitproxy.
  
#!/bin/sh
#
# Use socat to proxy git through an HTTP CONNECT firewall.
# Useful if you are trying to clone git:// from inside a company.
# Requires that the proxy allows CONNECT to port 9418.
#
# Save this file as gitproxy somewhere in your path (e.g., ~/bin) and then run
# chmod +x gitproxy
# git config --global core.gitproxy gitproxy
#
# More details at http://tinyurl.com/8xvpny
# Configuration. Common proxy ports are 3128, 8123, 8000.
#
_proxy=yourproxyhost
_proxyport=yourproxyport
exec socat STDIO PROXY:$_proxy:$1:$2,proxyport=$_proxyport

  
• Set the executable bit of the gitproxy file by using chmod +x /usr/local/bin/gitproxy command.
• Make sure /usr/local/bin is available in PATH environment variable for everybody (not just root).
• Configure git to use proxy setting by running the following command,
  $> git config --global core.gitproxy gitproxy

Git configuration: Make sure we have added username and email as part of git setup.

• $> git config --global user.name "Some super user name"
• $> git config --global user.email "Super user or admin email address"

Postgresql database configuration:

• Database template setup
  
  $> su - postgres     # This will change the user to postgres
$> psql template1 < /usr/share/postgresql/8.4/contrib/adminpack.sql # This will setup the postgresql database template
$> exit # Logout the postgres user. We are back to root user
   
• Change the password for postgres user. Choose a strong password for the postgres user ('postgres' is the admin user for Postgresql installation)
  
  $> password postgres
   
• Issue the following commands to set a password for the postgres administrative user. Be sure to replace mypassword with a strong password. This password will be used to connect to the database via the network; ident authentication will be used for local connections made with psql while logged into a shell as the postgres user. You may use the system password for 'postgres' again, here. If you have already done all these first-time postgresql setup, you can use the psql client directly.
  
  $> su - postgres
$> psql -c "ALTER USER postgres WITH PASSWORD 'mypassword'" -d template1
$> psql     # Start the postgresql client

  Now, you will get the psql prompt. Let's setup the database and user-role for Redmine here. postgres=# just indicates the postgresql client prompt. Replace the myredminepassword with a strong enough password for redmine db user.
  
  postgres=# CREATE ROLE redmine_user LOGIN ENCRYPTED PASSWORD 'myredminepassword' NOINHERIT VALID UNTIL 'infinity';
postgres=# CREATE DATABASE redmine_db WITH ENCODING='UTF8' OWNER=redmine_user;
postgres=# ALTER DATABASE "redmine_db" SET datestyle="ISO,MDY";

  Now we have the database for Redmine named, 'redmine_db' and the corresponding user-role for it named, 'redmine_user' having the password 'myredminepassword' (whatever you have replaced it with).
  

Redmine installation:

$> cd /opt
$> svn co http://redmine.rubyforge.org/svn/branches/2.0-stable redmine-2.0
$> mv redmine-2.0 redmine

Now, it is the time to setup configuration.xml and database.xml files for Redmine.

$> cd /opt/redmine/config
$> cp configuration.yml.sample configuration.yml

Open and edit the configuration.yml to setup your default email server and other Redmine specific configuration as per your need. Consult a system administrator for proper values for email server setup (SMTP) if needed. Rest of the parameters are self-explanatory.

$> cp database.yml.sample database.yml

Open and edit the database.yml to reflect just the following entries as below. Again, don't forget to replace "myredminepassword" with the one you have set earlier.

production:
  adapter: postgresql
  database: redmine_db
  host: localhost
  username: redmine_user
  password: "myredminepassword"
  encoding: utf8
  schema_search_path: public

$> cd /opt/redmine
$> gem install bundler

The executable 'budle' which is part of the bundler gem gets installed into /var/lib/gems/1.8/bin. Include this path into PATH environment variable, before proceeding further. Since, we are not interested in development, test, mysql and sqlite gem installations for Redmine, we are skipping those here.

$> bundle install --without development test mysql sqlite

Make sure the above command succeeds. Otherwise, install any additional *-dev packages using apt-get and retry the bundle command above.

$> export RAILS_ENV=production
$> rake generate_secret_token
$> rake db:migrate
$> rake redmine:load_default_data
$> rake tmp:cache:clear
$> rake tmp:sessions.clear


Installing and configuring Redmine Backlogs plugin for agile project management:

$> export RAILS_ENV=production
$> cd /opt/redmine/plugins
$> git clone git://github.com/backlogs/redmine_backlogs.git
$> cd /opt/redmine
$> bundle install --without development test mysql sqlite
$> rake redmine:backlogs:install

Make sure the 'bundle' command above succeeds again. This time it installs some additional gems required by backlogs plugin. For the last command which installs backlogs, please answer the questions which it prompts at the command prompt while it sets up the backlog for use with Redmine. You can change the settings later using the Redmine's user interface inside the browser.


Setting up nginx to serve Redmine ruby-on-rails application:

$> gem install passenger
$> passenger-install-nginx-module

Follow the command prompt instructions and choose to download, compile and install nginx with passenger support (which is the recommended setup). If you choose the default options, nginx will be installed in /opt/nginx folder.

$> cd /opt/nginx/html
$> ln -s /opt/redmine/public redmine

In Debian, www-data is the default web-server user, with a group of the same name. If it is not so in your case, adjust the web user and group values accordingly. Open the file /opt/nginx/conf/nginx.conf and edit the entries to reflect those shown below.

user  www-data;
worker_processes  1;

events {
    worker_connections  1024;
}


http {
    passenger_root /var/lib/gems/1.8/gems/passenger-3.0.17;
    passenger_ruby /usr/bin/ruby1.8;
    passenger_default_user www-data;
    passenger_default_group www-data;

    include       mime.types;
    default_type  application/octet-stream;

    sendfile        on;
    keepalive_timeout  65;

    gzip  on;

    server {
        listen       80;
        server_name  localhost;

        location / {
            root   html;
            index  index.html index.htm;

            passenger_enabled on;
            passenger_base_uri /redmine;
        }

        # redirect server error pages to the static page /50x.html
        #
        error_page   500 502 503 504  /50x.html;
        location = /50x.html {
            root   html;
        }
    }
}

Now, we need to change the web-user access to some of the Redmine directories.

$> cd /opt/redmine
$> chown -R www-data:www-data files tmp log public/plugin_assets
$> chmod -R 755 files tmp log public/plugin_assets

Well, we are almost done. We need to start the nginx server now.

$> /opt/nginx/sbin/nginx -c /opt/nginx/conf/nginx.conf

If all are fine, the last command will fireup the nginx web server, running our Redmine application. Open the browser and access redmine at http://localhost/redmine. Login to the redmine as user 'admin' with default password 'admin'. Now, you are free to configure Redmine as per your project needs. Wait! we still need to do one thing, especially if we are interested in accessing gitolite controlled git repositories from within Redmine (read access only).


Configuring Gitolite and allowing read access to Redmine:

Gitolite is not configured if you simply install it via apt-get. For it to work, we need to give it a user's rsa public key, who will act as gitolite-admin, thus controlling the repository creation, providing user access and so on. Let's say, we have a user by name 'sysadmin' in our system on which we just setup the Redmine. Let's choose this user as the gitolite-admin.

$> su - sysadmin
$> ssh-keygen -t rsa  #Just, type enter and do not set any passphrase
$> cp ~/.ssh/id_rsa.pub /tmp/sysadmin.pub  # Name of the .pub file should match the user name
$> exit # We are back to root / superuser
$> dpkg-reconfigure gitolite

Now, choose all the default values as shown in the ncurses based prompts which appear, except for admin key prompt where in you type, /tmp/sysadmin.pub. Then, gitolite will run additional setups automatically to configure sysadmin as the gitolite-admin.

$> su - gitolite # switch to gitolite user

Open and edit the file .gitolite.rc (under gitolite's home directory which is /var/lib/gitolite by default). Change the umask entries to reflect the following. By setting the umask to 0027 we are giving read access to the group 'gitolite' and hence, anybody who belongs to this group. We will soon include www-data as a member of this group.

# $REPO_UMASK = 0077;         # gets you 'rwx------'
$REPO_UMASK = 0027;       # gets you 'rwxr-x---'
# $REPO_UMASK = 0022;       # gets you 'rwxr-xr-x'

$> exit # We are back as root / superuser
$> adduser www-data gitolite # We have added www-data to gitolite group

Now, under those redmine projects which use git as the repository, we can view the repository contents, diffs and so on. Just stop and start the nginx server again.

$> /opt/nginx/sbin/nginx -s stop && sync
$> /opt/nginx/sbin/nginx -c /opt/nginx/conf/nginx.conf

Clone the gitolite-admin repository to manage rest of the git repositories through gitolite. I have assumed that sysadmin user will have a directory named 'Projects' under his HOME directory (assumed as /home/sysadmin) wherein he will clone the gitolite-admin repo.

$> su - sysadmin
$> mkdir -p ~/Projects
$> cd ~/Projects
$> git clone gitolite@localhost:gitolite-admin.git

Now, sysadmin user will have gitolite-admin repo under /home/sysadmin/Projects. Open edit the file conf/gitolite.conf uner gitolite-admin directory and remove the 'testing' repo configuration. Do not touch gitolite-admin stuff!! Then do a git commit and push as follows (We are in directory /home/sysadmin/Projects/gitolite-admin).

$> git add .
$> git commit -a -m "Removed testing repo"
$> git push origin master
$> exit # We are back as root / superuser

We need to manually remove the testing.git repository from gitolite user's repositories directory.

$> su - gitolite
$> cd ~/repositories
$> rm -rf testing.git

We remove the testing.git directory as this is a test repository with previous umask set. We can create another testing repo again, using gitolite-admin configuration. Remember, not to touch the gitolite-admin.git directory!

Well, we are done!! For further assistance on git and gitolite, please refer to http://git-scm.com/docs and https://github.com/sitaramc/gitolite/wiki/ respectively.