Originally I wanted to install Launchpad on my server to manage my projects. As of 17th of August of 2009, Launchpad is not yet ready for production. The only way to install it is using an script, only available for Ubuntu 9.04, which doesn't work too well on a server. I'll keep an eye on it as I like the way Canonical does things (and applications), but in the meantime I decided to use Redmine as I found Trac lacking on some areas.

Redmine

Redmine is an open source, web-based project management and bug-tracking tool, written in Ruby on Rails and heavily influenced by Trac. It improves on several areas, like providing multiple project support, integrating with several source control systems (from popular SVN to less popular Bazaar or Darcs) and allowing extension of its functionalities through plugins. This guide describes how to install Redmine in an Ubuntu 9.04 server using Mongrel as web server, Nginx as proxy and MySQL as database. To achieve this we have to follow 3 steps:

• install ruby and rails and MySQL
• install Redmine
• install Mongrel and Nginx

This guide can be adapted to older versions of Ubuntu and most Linux distributions, just replacing the tools/packages by the specific ones available in that distribution. The guide is a quick overview of the main steps, for  more information on configuration options check the documentation of the corresponding tool.

Install Ruby and Rails and MySQL

To install the components first ensure the system is up to date:

sudo apt-get update
sudo apt-get dist-upgrade

Then run the following command:

sudo apt-get install build-essential ruby ri rdoc mysql-server libmysql-ruby ruby1.8-dev irb1.8 libdbd-mysql-perl libdbi-perl
      libmysql-ruby1.8 libmysqlclient15off libnet-daemon-perl libplrpc-perl libreadline-ruby1.8 libruby1.8 rdoc1.8 ri1.8 ruby1.8
      irb libopenssl-ruby libopenssl-ruby1.8 libhtml-template-perl mysql-client-5.0 mysql-common mysql-server-5.0 mysql-server-core-5.0

Now that we have Ruby installed, we use Gems to install Rails:

sudo gem update
sudo gem install rails --no-rdoc –no-ri

The flags –no-rdoc and –no-ri are included to reduce the RAM footprint of the component, feel free to remove them if your machine has more than enough RAM. To finish this part, open the MySQL client and create the Redmine database:

create database redmine character set utf8;

Install Redmine

Get the code from the download page. Although the stable release is recommended, if you are going to use Bazaar the svn contains some fixes you want to use, so do an export from the trunk and use that. (Note: if you use the trunk, you'll have to install a newer Rails using Gems due to version requirements). Select a folder in your server (from now on, APP) and copy the downloaded code there. Move to the APP folder and run:

sudo cp config/database.yml.example config/database.yml
sudo cp config/email.yml.example config/email.yml

Edit the new yml files and change the configuration as required (MySQL details, mail server, etc).  Now run these commands to create the database and populate it:

rake db:migrate RAILS_ENV="production"
rake redmine:load_default_data RAILS_ENV="production"

We also need ImageMagick  (although is optional):

sudo apt-get install imagemagick libmagickwand-dev
sudo gem install rmagick

Install Mongrel and Nginx

To run Redmine we will use a standard setup for Rails applications, consistent on Mongrel as web server and Nginx as proxy that interacts with the network. We will run Mongrel as Mongrel Cluster, to improve the performance as Mongrel is single threaded and we will need multiple instances to server multiple clients. First we need to install Mongrel and Mongrel Cluster:

sudo gem install mongrel
sudo gem install mongrel_cluster

Now move to APP folder and run:

mongrel_rails cluster::configure -e production -p 8000 -N 2 -c APP -a 127.0.0.1

The flag -p indicates the initial port to use by Mongrel. Flag -N tells how many instances you want running in the cluster. Flag -a shows the bind address of the cluster. Once created, we need to set it up so it starts automatically with the server:

sudo mkdir /etc/mongrel_cluster
sudo ln -s APP/config/mongrel_cluster.yml /etc/mongrel_cluster/your-app-name.yml
sudo cp /var/lib/gems/1.8/gems/mongrel_cluster-1.0.5/resources/mongrel_cluster /etc/init.d/
sudo chmod +x /etc/init.d/mongrel_cluster
sudo /usr/sbin/update-rc.d mongrel_cluster defaults

Now you can control the cluster with the commands:

mongrel_cluster_ctl start
mongrel_cluster_ctl stop
mongrel_cluster_ctl restart

Now install nginx (if you don't have it):

sudo apt-get install nginx

We need to create a virtual host for Nginx, that will receive the requests and forward them to Redmine. Assuming your public domain will be “domain.com”:

sudo nano /usr/local/nginx/sites-available/domain.com

And copy inside:

upstream domain1 {

 server 127.0.0.1:5000;
 server 127.0.0.1:5001;
 server 127.0.0.1:5002;

}

server {

 listen   80;
 server_name  www.domain.com;
 rewrite ^/(.*) http://domain.com/$1 permanent;

}

server {

 listen   80;
 server_name domain.com;

 access_log /home/demo/public_html/railsapp/log/access.log;
 error_log /home/demo/public_html/railsapp/log/error.log;

 root   /home/demo/public_html/railsapp/public/;
 index  index.html;

 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 false;

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

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

      if (!-f $request_filename) {
        proxy_pass http://domain1;
        break;
      }

 }
}

Be careful to change the port numbers and domain name to the ones you'll use on your server. Now enable the site:

sudo ln -s /usr/local/nginx/sites-available/domain.com /usr/local/nginx/sites-enabled/domain.com

and once you restart Nginx your Redmine installation is ready to go. Configure Bazaar First we need to edit the file config/environment.rb to add new environment variables related to Python, to avoid problems while accessing Bazaar:

ENV['PYTHONPATH'] = '/usr/lib/python2.6'
ENV['PATH'] = "#{ENV['PATH']}:/usr/bin"

When you create a project you just need to point Redmine to your Bazaar main folder, this will allow you to browse the repository. Be aware it still has some limitations when displaying contents, but it works quite well. To work with Bazaar, let's set up a repository on  our server. This will be a dumb repository, it means is nothing more than a  folder that can be accessed via sftp that stores the data of the repository. First of all, in Ubuntu 9.04 (our server) let's install the needed tools (sftp) and enable them as accepted shell:

$apt-get install ssh openssh-server
$echo '/usr/lib/sftp-server' >> /etc/shells

Then create a user to connect via sftp to the server:

$sudo useradd --create-home --home-dir /home/bzr --shell /usr/lib/sftp-server bzr

And that's it, we have a folder (/home/bzr/) ready to receive our Bazaar projects. Is a good practice to give write rights to that folder to members of group “bzr”, and to add a password to the 'bzr' user. On your client machine, install Bazaar (using apt-get or similar). Then download the Uploader plugin which eases the task to commit changes to “dumb servers”:

$ mkdir /home/pvillega/.bazaar/plugins
$ bzr co lp:bzr-upload ~/.bazaar/plugins/upload

or if you use Ubuntu/Debian with:

$sudo apt-get install bzr-upload

Then create the base repository. There are two ways of doing this, you can create a shared repository which stores every child branch revision, or you can create standalone repositories, which are good if you don’t want to share revision information with other branches. Here we create a shared repository:

bzr init-repository some_directory
bzr init some_directory/trunk
bzr init some_directory/branches

Now, to interact with the server we created before, first run:

bzr push --create-prefix sftp://bzr@server:port/~/test

This pushes the project to the server and creates the folder 'test' if needed. After that, all the interaction with the server can be (usually) reduced to:

 bzr pull sftp://bzr@server:port/~/test   #update changes from the server to our client
 bzr co sftp://bzr@server:port/~/test      #checkout the project
 bzr push sftp://bzr@server:port/~/test  #push changes to the server

Ok, is not the nicest way to do that, but remember this is a distributed repository, you won't update or push changes too often, usually only when you are done with a piece of work.  There's an alternative method, using what is called a “smart server”, which is faster than the previous way (but not always possible to use for several reasons). In this case we will use an ssh connection to communicate with the repository, but this requires that our user belongs to the group “bzr” to be able to write in that folder. The command for the first commit is:

bzr push --create-prefix bzr+ssh://server:port/home/bzr/test #requires full path, from root

In a similar way we interact with the server using:

 bzr pull bzr+ssh://bzr@server:port/~/test   #update changes from the server to our client
 bzr co bzr+ssh://bzr@server:port/~/test      #checkout the project
 bzr push bzr+ssh://bzr@server:port/~/test  #push changes to the server

Install Redmine Themes

You can install some new themes for Redmine, available at here. Although is mainly a cosmetic change, some themes provide enhancements like colouring tickets according to priority and they are really easy to manage. For example, to install the Basecamp theme:

1. Download application.css
2. Create required directories: mkdir -p redmine/public/themes/basecamp/stylesheets
3. Copy downloaded file:  cp application.css redmine/public/themes/basecamp/stylesheets

That's it .. now restart your instance running Redmine and select the new basecamp theme from /settings

Install Redmine Plugins

Redmine provides several plugins that enhance the capabilities of the tool. Amongst them you can find some nice ones like:

• Bots Filter: avoids bots from accessing certain areas of the application
• Charts: adds some project based charts
• Exception Handler: notifies admins when an exception occurs
• Hudson: integrates Redmine and Hudson, allowing you to see Hudson reports
• Status updates: allows users to say what are they doing, kind of Twitter per project.
• Vote: allows users to vote on issues so you see which ones are important to them

You can find these and many more in this page . To install a plugin, follow the instructions on the “Installation” section of its page. Then restart Redmine and you are good to go.

Connect Mylyn to Redmine

If you use Mylyn (and you should!) use these instructions to connect it to your Redmine repository.

Introduction

Requirements

This document assumes you are using an Ubuntu 8.04 server. This guide can be probably used with newer versions of Ubuntu and Debian, but some minor changes may be required. We will install Trac 0.11. It requires:

• Python 2.5
• PostgreSQL as database (Trac 0.11 has some bugs when using MySQL).
• Nginx as HTTP-proxy (Apache could be used but this configuration is simpler to setup and runs faster)

It is recommended you apply all available patches (security and upgrade) to your server before proceeding.

Postgres

If you don't have Postgres installed in your server you can follow these instructions before proceeding with the installation. To install Postgres and all required packages run:

$ sudo apt-get install postgresql postgresql-client postgresql-contrib python-psycopg2

This will deploy the database, create the link so it runs as daemon and configure the "postgres" user (root user of the database). It will also add the Python libraries so we can access the database from Trac. Once installed, we need to change the default "postgres" password. To do that execute:

$ sudo su postgres -c psql template1

This will log you into the PostgreSQL console. There run:

template1=# ALTER USER postgres WITH PASSWORD 'new_password';

Now we need to set the password for the Ubuntu postgresql user. Execute:

$ sudo passwd -d postgres
$ sudo su postgres -c passwd

Now restart the server.

$ sudo /etc/init.d/postgresql-8.3 restart

The server should be running, try to log again using:

$ sudo su postgres -c psql template1

Be aware this has created a database server which only has localhost access, so it won't be available from other servers. If you want to allow connection from an external ip, you have to edit pg_hba.conf.

Installation steps

Those steps assume you have an user with "sudo" privileges. You only need a console, no UI required.

Installing Trac

First of all we need some packages before we install Trac. Run:

$ sudo apt-get install build-essential graphviz apache2-utils htmldoc enscript

Once those components are installed, you can install Trac using "easy_install", the Python installer. Run:

$ sudo easy_install Trac
$ sudo easy_install http://svn.edgewall.org/repos/genshi/trunk/  #A required component, install after Trac to avoid problems

Now you can configure the database and create the Trac user. Log into PostgreSQL:

$ su postgres -c psql

and run:

template1=# create user
 with password 'user_password';
template1=# create database
 with owner=user
 encoding = 'utf8';

$ trac-admin /public/projectname initenv

This will ask some questions about the project. When you are asked for the PostgreSQL connection string, write:

postgres://trac_db_user:password@localhost:5432/database

You are done, your Trac server is configured and ready to go. To test it, use the embedded Trac server:

$ tracd -p 3050 /public/projectname

Be aware this (probably) can't be accessed from outside your box as the port will be closed. Just check it works with Lynx or a similar browser.

Use nginx as proxy

As said before, the server is not yet available from outside the box (if it is, you have a security issue here!). Setting Nginx as proxy is quite easy. Go to your "nginx/sites-available" folder and edit the file of the domain you will use to access the Trac server. You can use this configuration as an example:

upstream domain_trac {
          server  127.0.0.1:3050;
 } 

server {
            listen   80;
            server_name  domain.com;
            rewrite ^/(.*) http://www.domain.com/$1 permanent;
           } 
server {
            listen   80;
            server_name www.domain.com; 
            access_log /home/public_html/domain.com/log/access.log;
            error_log /home/public_html/domain.com/log/error.log; 

            location / {
                        proxy_pass      http://domain;
			proxy_redirect  default;
                        }
      }

Restart Nginx and you are done. Nginx will be a simple proxy of your "tracd" server, redirecting all the requests received. This is a more flexible and fast configuration than the one using mod_cgi on Apache or a similar server. Also it allows you to kill an instance of Trac easily and without affecting other running Trac instances under the same proxy.

Enabling user authentication

Probably you want some privacy for your project, or simply avoiding anybody can edit the wiki. To this end you can enable user authentication. This section does a brief description, you will find more detail at your own Trac server, under http://www.domain.com/ProjectName/wiki/TracStandalone. User authentication is based on basic HTTP authentication, using Apache password files. Go to your root ("/public/") folder and run:

$ sudo htpasswd -c /public/ProjectName/.htpasswd username

This will request the password of the user and save it in the .htpasswd file. You can select another path outside the project folder if you want, but it has to be accessible by nginx and tracd. Now you have to notify Trac that you own a password file and want to use it for authentication. To this end, you have to launch the Trac server with some parameters:

$ tracd -p 3050 --basic-auth=ProjectName,/public/ProjectName/.htpasswd,domain.com /public/ProjectName/

Add Admin user

Once you enable authentication, there is no default admin user. You need to add at least one user to the admin group to be able to configure Trac properly. Run:

$ trac-admin /public/ProjectName/ permission add  TRAC_ADMIN

Be careful, <user> has to be an existing user with a valid password in the .htpasswd file. For more details, check your own Trac instance at http://www.domain.com/ProjectName/wiki/TracPermissions

Running multiple projects at once

As said before, Trac only allows one project per environment (folder). If you want to manage more projects, you have to create new folders under the root directory (in this tutorial, "/public/") and initialize each one independently. Then you can tell tracd to run them all at once. If you want to share the access permissions between all the projects, run:

$ tracd -p 8080 --auth="*",/public/ProjectName/.htpasswd,domain.com  /public/project1 /public/project2

For other configurations check your own Trac instance at http://www.domain.com/ProjectName/wiki/TracStandalone

Integrate with Git

As it is now, our Track instance only provides a Wiki and a ticketing system. To use the full power of Trac we need to link some code repository to it. Our choice is Git for several reasons (performance, usage, etc). This assumes you have installed a Gitosis repository in your server that can be used to store the git code. The integration is done using the Git plugin for Trac, available at http://trac-hacks.org/wiki/GitPlugin. This page also contains steps to install the plugin. You just need to download the zip file, unzip it and run:

$ cd gitplugin/0.11/
$ sudo easy_install .

Once the plugin is installed, our next step is to clone the Gitosis administration file and edit it:

$ git clone git@YOUR_SERVER_HOSTNAME:gitosis-admin.git
$ cd gitosis-admin
$ nano gitosis.conf

Add the new group and repository related to the project:

[group coreteam]
writable = projectname
members = username@desktop

and commit the changes to the Gitosis server:

$ git commit -a -m "allowing access to projectname to user username"
$ git push

Now create your initial repository:

$ mkdir projectname
$ cd projectname
$ git init
$ git remote add origin git@YOUR_SERVER_HOSTNAME:projectname.git
  # do some work
$ git add new files
$ git commit -a -m "first commit"
$ git push origin master:refs/heads/master

You have created your repository and submitted the first files. Now log into your Gitosis server and edit the file "gitosis/repositories/projectname/description". Change the content as required and set its owner to "git:webmasters" (chown). This step is important to avoid issues when pushing new code to the repository. Now you just need to edit "/public/projectname/conf/trac.ini" and add the references to git:

[components]
tracext.git.* = enabled
[git]
cached_repository = true
git_bin = /usr/bin/git
persistent_cache = true
shortrev_len = 7
[trac]
repository_dir = /home/git/repositories/game.git
repository_type = git

Configuration

Now that we have a running Trac instance, we have to configure it. You should check your Trac documentation at http://www.domain.com/ProjectName/wiki/TracIni to see what kind of customizations you can do using the "trac.ini" file (for example, sending emails to users).

Change reporting system

The default ticket reports are not very user-friendly. To fix that and use a better system, edit "trac.ini":

[components]
trac.ticket.report.* = disabled

Add Spam filter

If you allow anonymous users to edit your content, you will probably need a spam filter. The one we will use needs an Akismet key to filter spam. To install it run:

$ sudo easy_install TracSpamFilter

Once installed, edit "trac.ini" and add:

[akismet]
api_key = 1234567890

Enable XML-RPC

XML-RPC allows 3rd party applications to connect to Trac. This is required if you will use Netbeans or Eclipse to interact with Trac. The offical plugin is located at http://trac-hacks.org/wiki/XmlRpcPlugin, but it has some issues with custom workflows, which causes problems with the Cube'N plugin of Netbeans. As we use Netbeans, we need to use the fixed pluguin from http://code.google.com/p/cubeon/downloads/list, TracXMLRPC-1.5.0-py2.5.egg. Download the file and install it using:

$ sudo easy_install racXMLRPC-1.5.0-py2.5.egg

Then edit trac.ini and add:

[components]
tracrpc.* = enabled

Restart Trac.

Running Trac as daemon

There are some scripts to launch Trac (using tracd) as a Linux daemon, but the few I've tested have issues when running under Ubuntu. The easiest solution is to launch tracd using “nohup”. This should suffice for most user. When I find a working init.d script I will copy it here.

Static content

For performance reasons, static content (like non-code files) should be put in the $TRAC_ENV/htdocs folder, and is accessed by URLs like <project_URL>/chrome/site/.... There's a wiki label for them: "htdocs:file_name".