Redmine

h1. HowTo Install Redmine 1.2.x with Mercurial and Subversion on Ubuntu Server 10.04

{{toc}}

h2. Redmine Installation

# Install the LAMP stack

<pre>

$ sudo tasksel install lamp-server

</pre>

# Install the required packages

<pre>

$ sudo apt-get install build-essential subversion llibmysqlclient15-dev libdigest-sha1-perl libgemplugin-ruby libgemplugin-ruby1.8 libruby-extras libruby1.8-extras rails rake ruby rubygems rubygems1.8 ruby1.8-dev libopenssl-ruby1.8 

</pre>

# Install the required Ruby gems

<pre>

$ sudo gem install rails -v=2.3.11 --no-ri --no-rdoc

$ sudo gem install rake -v=0.8.7 --no-ri --no-rdoc

$ sudo gem uninstall rake -v=0.9.2 

$ sudo gem install i18n -v=0.4.2 --no-ri --no-rdoc

$ sudo gem install mysql --no-ri --no-rdoc

</pre> 

# Download Redmine into /user/share/redmine directory

<pre>

$ sudo svn co http://redmine.rubyforge.org/svn/branches/1.2-stable /usr/share/redmine

</pre>

# Create an empty MySQL database and accompanying user named redmine for example.

<pre>

$ mysql -u root -p

(enter the mysql root user password)

> create database redmine character set utf8;

> create user 'redmine'@'localhost' identified by '[password]';

> grant all privileges on redmine.* to 'redmine'@'localhost' identified by '[password]';

> exit

</pre>

# Copy config/database.yml.example to config/database.yml and edit this file in order to configure your database settings for "production" environment.

<pre>

$ sudo cp /usr/share/redmine/config/database.yml.example /usr/share/redmine/config/database.yml

$ sudo nano /usr/share/redmine/config/database.yml

Modify to the following and save (ctrl+x)

production:

  adapter: mysql

  socket: /var/run/mysqld/mysqld.sock

  database: redmine

  host: localhost

  username: redmine

  password: [password]

  encoding: utf8

</pre>

# Generate a session store secret.

<pre>

$ cd /usr/share/redmine

$ sudo rake generate_session_store

</pre>

# Create the database structure, by running the following command under the application root directory:

<pre>

$ cd /usr/share/redmine

$ sudo rake db:migrate RAILS_ENV="production" 

</pre>

# Insert default configuration data in database, by running the following command:

<pre>

$ sudo RAILS_ENV=production rake redmine:load_default_data

</pre>

# Setting up permissions

<pre>

$ cd /usr/share/redmine

$ sudo chown -R www-data:www-data files log tmp public/plugin_assets

$ sudo chmod -R 755 files log tmp public/plugin_assets

</pre>

# Test using the webrick web server

<pre>

$ cd /usr/share/redmine

$ ruby script/server webrick -e production

Point your web browser at http://[my server ip]:3000

You should now see the application welcome page.

</pre>

h2. Apache Integration

# Install the required packages

<pre>

$ sudo apt-get install libapache2-mod-passenger

</pre>

# Add a symbolic link to the public redmine web directory

<pre>

$ sudo ln -s /usr/share/redmine/public /var/www/redmine

</pre>

# Configure Passanger to run as www-data

<pre>

$ sudo nano /etc/apache2/mods-available/passenger.conf

Add the follow line and save (ctrl+x)

PassengerDefaultUser www-data

</pre>

# Create a new Apache site file

<pre> 

$ sudo nano /etc/apache2/sites-available/redmine 

</pre>

Add the following lines and save (ctrl+x)

<pre>

<VirtualHost *:80>

        ServerAdmin webmaster@localhost

        DocumentRoot /var/www

        ServerName myservername

        RewriteEngine on

        RewriteRule   ^/$  /redmine  [R]

        <Directory /var/www/redmine>

                RailsBaseURI /redmine

                PassengerResolveSymlinksInDocumentRoot on

        </Directory>

        ErrorLog /var/log/apache2/error.log

        # Possible values include: debug, info, notice, warn, error, crit,

        # alert, emerg.

        LogLevel warn

        CustomLog /var/log/apache2/access.log combined

</VirtualHost>

</pre>

For SSL add the following text instead

<pre>

<VirtualHost *:443>

        ServerAdmin webmaster@localhost

        DocumentRoot /var/www

        ServerName myservername

        SSLEngine On

        SSLCertificateFile /etc/apache2/ssl/redmine.pem

        RewriteEngine on

        RewriteRule   ^/$  /redmine  [R]

        <Directory /var/www/redmine>

                RailsBaseURI /redmine

                PassengerResolveSymlinksInDocumentRoot on

        </Directory>

        ErrorLog /var/log/apache2/error.log

        # Possible values include: debug, info, notice, warn, error, crit,

        # alert, emerg.

        LogLevel warn

        CustomLog /var/log/apache2/access.log combined

</VirtualHost>

</pre>

# Enable the Redmine website

<pre>

$ sudo a2dissite default

$ sudo a2ensite redmine

</pre> 

# Enable the Passenger and Rewite modules and restart Apache

<pre>

$ sudo a2enmod passenger

$ sudo a2enmod rewrite

$ sudo /etc/init.d/apache2 restart

</pre> 

# Test the setup

<pre>

Open up your favorite web browser and goto

http://[my site or ip]/redmine

</pre>

h2. Mercurial Integration

# Install the latest Mercurial release 

<pre>

$ sudo apt-get install python-software-properties

$ sudo add-apt-repository ppa:mercurial-ppa/releases

$ sudo apt-get update

$ sudo apt-get install mercurial libapache-dbi-perl libapache2-mod-perl2

</pre>

# Create the hg web directory

<pre>

$ sudo mkdir -p /var/hg/repos

</pre>

# Create the web cgi script file

<pre>

$ sudo nano /var/hg/hgwebdir.cgi

Add the following and save

#!/usr/bin/env python

#

from mercurial import demandimport; demandimport.enable()

from mercurial.hgweb.hgwebdir_mod import hgwebdir

import mercurial.hgweb.wsgicgi as wsgicgi

application = hgwebdir('hgweb.config')

wsgicgi.launch(application)

</pre>

# Create the cgi web config file 

<pre>

$ sudo nano /var/hg/hgweb.config

Add the following and save

[paths]

/=/var/hg/repos/**

[web]

allow_push = *

push_ssl = false

allowbz2 = yes

allowgz = yes

allowzip = yes

</pre>

# Setup permissions

<pre>

$ sudo chown -R www-data:www-data /var/hg

$ sudo chmod gu+x /var/hg/hgwebdir.cgi

</pre>

# Create a Apache config file

<pre>

$ sudo nano /etc/apache2/conf.d/hg.config

Add the following and save

PerlLoadModule Apache::Redmine

ScriptAlias /hg  "/var/hg/hgwebdir.cgi"

<Location /hg  >

	AuthType Basic

	AuthName "Redmine Mercurial Repository" 

	Require valid-user

	#Redmine auth

	PerlAccessHandler Apache::Authn::Redmine::access_handler

	PerlAuthenHandler Apache::Authn::Redmine::authen_handler

	RedmineDSN "DBI:mysql:database=redmine;host=localhost" 

	RedmineDbUser "redmine" 

	RedmineDbPass "password" 

</Location>

</pre>

# Add a symbolic link to Redmine.pm

<pre>

$ sudo ln -s /usr/share/redmine/extra/svn/Redmine.pm /usr/lib/perl5/Apache/Redmine.pm

$ sudo ln -s /usr/share/redmine/extra/svn/Redmine.pm /usr/lib/perl5/Apache2/Redmine.pm  

</pre>

# Enable the required Apache modules and restart Apache

<pre>

$ sudo /etc/init.d/apache2 restart

</pre>

# Create a new test repository and project in Redmine

<pre>

$ sudo hg init /var/hg/repos/test

$ sudo chown -R www-data:www-data /var/hg/repos/test

Create a new project with and identifier 'test'

In the project Settings > Repository set

SCM: Mercurial

Path to repository: /var/hg/repos/test

Press the 'Create' button

Goto to the Repository tab of the test project

</pre>

# View the test repository in the web browser 

<pre>

> http://[my site name]/hg/test

</pre>

h2. Subversion Integration

# Install the latest Mercurial release 

<pre>

$ sudo apt-get install subversion libapache2-svn libapache-dbi-perl libapache2-mod-perl2

</pre>

# Create the svn repository directory

<pre>

$ sudo mkdir /var/svn

</pre>

# Setup permissions

<pre>

$ sudo chown -R www-data:www-data /var/svn

</pre>

# Add a symbolic link to Redmine.pm

<pre>

$ sudo ln -s /usr/share/redmine/extra/svn/Redmine.pm /usr/lib/perl5/Apache/Redmine.pm

$ sudo ln -s /usr/share/redmine/extra/svn/Redmine.pm /usr/lib/perl5/Apache2/Redmine.pm  

</pre>

# Create a Apache config file

<pre>

$ sudo nano /etc/apache2/conf.d/svn.config

</pre>

Add the following and save

<pre>

PerlLoadModule Apache::Redmine

<Location /svn>

	DAV svn

	SVNParentPath "/var/svn" 

	Order deny,allow

	Deny from all

	Satisfy any

	PerlAccessHandler Apache::Authn::Redmine::access_handler

	PerlAuthenHandler Apache::Authn::Redmine::authen_handler

	AuthType Basic

	AuthName "Redmine Subversion Repository" 

	#read-only access    

	<Limit GET PROPFIND OPTIONS REPORT>

		Require valid-user

		Allow from [my server ip]

		# Allow from another-ip

		 Satisfy any

	</Limit>

		# write access

		<LimitExcept GET PROPFIND OPTIONS REPORT>

		Require valid-user

	</LimitExcept>

	## for mysql

	RedmineDSN "DBI:mysql:database=redmine;host=localhost" 

	RedmineDbUser "redmine" 

	RedmineDbPass "password" 

</Location>

</pre>

# Enable the required Apache modules and restart Apache

<pre>

$ sudo a2enmod dav_svn

$ sudo /etc/init.d/apache2 restart

</pre>

# Create a new test repository

<pre>

$ sudo svnadmin create /var/svn/test

$ sudo chown -R www-data:www-data /var/svn/test

</pre>

h2. Automate Repository Creation

# Enable WS for repository management and generate and API key

<pre>

* From the Redmine Administration menu select Settings

* Click on the Repositories tab

* Enable the 'Enable WS for repository management' checkbox

* Click the 'Generate a key' link 

* Press the 'Save' button

</pre>

# Modify reposman.rb

<pre>

$ sudo nano /usr/share/extra/svn/reposman.rb

Add the following to module SCM and save  

  module Mercurial

    def self.create(path)

      Dir.mkdir path

      Dir.chdir(path) do

        system_or_raise "hg init"

      end

    end

  end

</pre>

# Schedule the reposman.rb script to run every minute

<pre>

$ sudo nano /etc/cron.d/redmine

</pre>

Add one of the following lines (not both) and save.

(Note: you will need to replace [my API key]  with the API key you generated in step 1) 

.

To create subversion repositories add:

<pre>

* * * * * root ruby /usr/share/redmine/extra/svn/reposman.rb --redmine localhost/redmine --scm Subversion --svn-dir /var/hg/repos --owner www-data --url file:///var/svn --key=[my API key] >> /var/log/reposman.log

</pre>

OR to create Mecurial repositories add:

<pre>

* * * * * root ruby /usr/share/redmine/extra/svn/reposman.rb --redmine localhost/redmine --scm Mercurial --svn-dir /var/hg/repos --owner www-data --url /var/hg/repos --key=[my API key] >> /var/log/reposman.log

</pre>

h2. Automatic refresh of repositories in Redmine

# Schedule the fetch_changesets script to run every 15 minutes

<pre>

$ sudo nano /var/cron.d/redmine

Add the following line and save

*/15 * * * * root ruby /usr/share/redmine/script/runner "Repository.fetch_changesets" -e production > /dev/null 2>&1

</pre>

# Setup a changegroup script on the Mercurial server to run fetch_changesets after each push to a Mercurial repository 

<pre>

$ sudo nano /var/hg/changegroup-hook

</pre>

Add the following text and save

(Note: you will need to replace [your API key] the API key you generated in Redmine

<pre>

#!/bin/sh

curl "http://localhost/redmine/sys/fetch_changesets?key=[your API key]"  > /dev/null 2>&1

</pre>

Setup permissions

<pre>

$ sudo chown www-data:www-data /var/hg/changegroup-hook

$ sudo chmod ug+x /var/hg/changegroup-hook

</pre>

Modify the hgweb.config file

<pre>

$ sudo nano /var/hg/hgweb.config

</pre>

Add the following section and save

<pre>

[hooks]

changegroup = /var/hg/changegroup-hook

</pre>

h2. Email Integration

# Install and configure Sendmail

<pre>

$ sudo apt-get install sendmail

$ sudo sendmailconfig

(Answer Yes to all questions which you will be asked)

</pre>

# Update the Redmine configuration file

<pre>

$ sudo nano /usr/share/redmine/config/configuration.yml

Add the following text and save

 production:

   email_delivery:

     delivery_method: :sendmail

</pre>

h2. Backup to Amazon S3 cloud storage

# Create an account at http://aws.amazon.com/ 

# Create a S3 bucket using the aws management console https://console.aws.amazon.com/ec2/home

# View your Access Keys at https://aws-portal.amazon.com/gp/aws/developer/account/index.html?action=access-key

# Build and install fuse to 2.8.4

<pre>

$ sudo wget https://launchpad.net/ubuntu/+archive/primary/+files/fuse_2.8.4.orig.tar.gz

$ cd fuse-2.8.4/

$ tar xzf fuse_2.8.4.orig.tar.gz 

$ sudo ./configure 

$ sudo make

$ sudo make install

</pre>

# Build and install s3fs 1.61 

<pre>

$ sudo apt-get install libxml2-dev

$ wget http://s3fs.googlecode.com/files/s3fs-1.61.tar.gz

$ tar xzf s3fs-1.61.tar.gz 

$ cd s3fs-1.61/

$ sudo ./configure 

$ sudo make

$ sudo make install

</pre>

# Setup s3fs password file

<pre>

$ sudo nano /etc/passwd-s3fs

</pre>

Added your 'Access Key ID' and 'Secret Access Key' separated by a colon

<pre>

[accessKeyId]:[secretAccessKey]

</pre>

Setup permissions

<pre>

sudo chmod 650 /etc/passwd-s3fs

</pre> 

# Create mounting point

<pre>

$ sudo mkdir /mnt/s3

</pre>

#Mount your S3 bucket

<pre>

$ sudo s3fs [your-s3-bucket-name] /mnt/s3 -ouse_cache=/tmp -o allow_other

</pre>

# Test it worked

<pre>

$ echo hello > welcome.txt

$ ls /mnt/s3

</pre>

# Create upstart job to mount the s3 file system start up

<pre>

$ sudo nano /etc/init/s3.conf

</pre>

Add the following text and save.

<pre>

description "Mount Amazon S3 file system and on system start"

start on (local-filesystems and net-device-up IFACE!=lo)

stop on runlevel [016]

respawn

exec s3fs -f [your-s3-bucket-name] /mnt/s3 -ouse_cache=/tmp -o allow_other

</pre>

# Create the backup script file

<pre>

$ sudo nano /usr/local/bin/backup-redmine

Add the following text and save.

#!/bin/bash

####################################

#

# Backup Redmine to S3 mount script with

# grandfather-father-son rotation.

#

####################################

# Dump the redmine database

mkdir /var/redmine-database-backup 2> /dev/null

mysqldump --user=redmine --password=[your-db-password] --single-transaction redmine > /var/redmine-database-backup/redmine-db-dump.sql

# What to backup. 

backup_files="/var/redmine-database-backup /usr/share/redmine/files /var/hg /etc/apache2/conf.d /etc/apache2/sites-available"

# Where to backup to.

dest="/mnt/s3"

# Setup variables for the archive filename.

day=$(date +%A)

hostname=$(hostname -s)

# Find which week of the month 1-4 it is.

day_num=$(date +%d)

if (( $day_num <= 7 )); then

        week_file="$hostname-week1.tgz"

elif (( $day_num > 7 && $day_num <= 14 )); then

        week_file="$hostname-week2.tgz"

elif (( $day_num > 14 && $day_num <= 21 )); then

        week_file="$hostname-week3.tgz"

elif (( $day_num > 21 && $day_num < 32 )); then

        week_file="$hostname-week4.tgz"

fi

# Find if the Month is odd or even.

month_num=$(date +%m)

month=$(expr $month_num % 2)

if [ $month -eq 0 ]; then

        month_file="$hostname-month2.tgz"

else

        month_file="$hostname-month1.tgz"

fi

# Create archive filename.

if [ $day_num == 1 ]; then

        archive_file=$month_file

elif [ $day != "Saturday" ]; then

        archive_file="$hostname-$day.tgz"

else 

        archive_file=$week_file

fi

# Print start status message.

echo "Backing up $backup_files to $dest/$archive_file"

date

echo

# Backup the files using tar.

tar czfP $dest/$archive_file $backup_files

# Print end status message.

echo

echo "Backup finished"

date

# Long listing of files in $dest to check file sizes.

ls -lh $dest/

</pre>

# Setup permissions 

<pre>

sudo chmod ug+x /usr/local/bin/backup-redmine

</pre>

# Schedule the backup to run once a day at 12am

<pre>

$ sudo nano /etc/cron.d/redmine

Add the following line and save

0 0 * * * root /usr/local/bin/backup-redmine

</pre>

# Test the script

<pre>

$ sudo backup-redmine

</pre>