Redmine

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

{{toc}}

h2. Pre-install

# Set the timezone

<pre>

$ dpkg-reconfigure tzdata

Select your timezone and exit.

</pre>

# Set your hostname

<pre>

$ sudo nano /etc/hostname

Enter your server name and save.

eg.

redmine

</pre>

# Map your fully qualified domain name (FQDN) to localhost

<pre>

$ sudo nano /etc/hosts

Add a line mapping local host to your FQDN and hostname and save. 

eg. 

127.0.0.1 redmine.domain.com redmine

</pre>

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 libmysqlclient-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>

-->Update rubygems

In some cases the your system will still be using rubygems 1.5, but you will need a later version. Check which version is installed by typing:

<pre>

$ gem --version

</pre>

If the version is 1.5: update rubygems

<pre>

gem install rubygems-update

cd /var/lib/gems/1.8/bin

sudo ./update_rubygems

</pre>

-->Install necessary gems

<pre>

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

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

$ sudo gem uninstall rake -v=0.9.2.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.3-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

</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

# Use PerlLoadModule Apache2::Redmine when using apache2, or else you might get weird errors trying to authenticate.

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/redmine/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/svn --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 /etc/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>

# Create a 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 640 /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 and unmount

<pre>

$ echo hello > /mnt/s3/welcome.txt

$ ls /mnt/s3

$ sudo umount /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 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>

# Start the s3 job

<pre>

sudo start s3

</pre>

# Test it worked

<pre>

$ echo hello > /mnt/s3/welcome2.txt

$ ls /mnt/s3

</pre>

# Create the backup script file

<pre>

$ sudo apt-get install mailutils

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

</pre>

Add the following text and save.

<pre>

#!/bin/bash

# Script to backup Redmine files to a mounted storage device

# with daily, weekly, monthly backup rotation

# Sysadmin email address

sysadmin_email="admin@domain.com"

# What to backup

db_dump_file="/usr/share/redmine/db/redmine-database-dump.sql"

backup_files="$db_dump_file /usr/share/redmine/files /var/hg /var/svn /etc/apache2/conf.d/hg.conf"

backup_files="$backup_files /etc/apache2/sites-available/redmine /etc/init/s3.conf /etc/cron.d/redmine"

backup_files="$backup_files /usr/local/bin/backup-redmine.sh"

# Where to backup to

backup_dir="/mnt/s3"

# Set database access

redmine_db_name="redmine"

redmine_db_user="redmine"

redmine_db_password="password"

# Encryption

encrypt="true"

secret_passphrase="password"

# Set rotation schedule in units of days ( 0 = disabled )

daily_remove_older_than=6

weekly_remove_older_than=31

monthly_remove_older_than=62

# Redirect stderr to a log file

error_log="/tmp/backup-redmine.log"

exec 6>&2

exec 2>$error_log

on_exit() {

    # Restore IO output

    exec 2>&6  6>&-

    # Check for errors

    if [ -s "$error_log" ]; then

        logger -t "$0" -s "#### Backup Failed ####"

        logger -t "$0" -s -f "$error_log"

        cat "$error_log" | mail -s "Backup failed!"  $sysadmin_email

     else

        logger -t "$0" -s "Backup Complete"

    fi

    # Clean up

    rm -f $error_log

}

trap on_exit EXIT SIGHUP SIGINT SIGQUIT SIGTERM

# Setup variables for the archive filename.

hostname=$(hostname -s)

date_stamp=`date +%Y-%m-%d`                    # Date p e.g 2011-12-31

date_day_of_week=`date +%A`                    # Day of the week e.g. Monday

date_day_of_month=`date +%e`                   # Date of the Month e.g. 27

# Is the  backup directory mounted?

mount | grep -sq "$backup_dir"

if  [ $? != 0 ]; then

   echo "backup destination ${backup_dir} is not mounted" >&2

  exit 1

fi

# Delete old archives

find "${backup_dir}" -mtime +"$monthly_remove_older_than" -type f -name "${hostname}_fullbackup_monthly*" -exec rm {} \;

find "${backup_dir}" -mtime +"$weekly_remove_older_than" -type f -name "${hostname}_fullbackup_weekly*" -exec rm {} \;

find "${backup_dir}" -mtime +"$daily_remove_older_than" -type f -name "${hostname}_fullbackup_daily*" -exec rm {} \;

# Determine the backup schedule

if [[ $monthly_remove_older_than -gt "0" && $date_day_of_month == "1" ]]; then

    schedule="monthly"

elif [[ $weekly_remove_older_than -gt "0" && $date_day_of_week == "Saturday" ]]; then

    schedule="weekly"

elif [[ $daily_remove_older_than -gt "0" ]]; then

    schedule="daily"

else

    echo "Invalid backup rotation schedule" >&2

    exit 1

fi

archive_file="${backup_dir}/${hostname}_fullbackup_${schedule}_${date_stamp}.tgz"

# Dump the redmine database

rm -f "${db_dump_file}"

mysqldump --user="${redmine_db_name}" --password="${redmine_db_password}" "${redmine_db_name}" > $db_dump_file

# Write the archive file to the backup directory

if [ $encrypt == "true" ]; then

    tar czP ${backup_files} | gpg -c -z 0 --yes --no-use-agent --passphrase="${secret_passphrase}" -o "${archive_file}.gpg"

else

    tar czfP "${archive_file}" ${backup_files}

fi

if [ -s "$error_log" ]; then

    exit 1

else

    exit 0

fi

</pre>

# Setup permissions 

<pre>

sudo chmod 770 /usr/local/bin/backup-redmine.sh

</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.sh

</pre>

# Test the script

<pre>

$ sudo backup-redmine.sh

$ ls -R /mnt/s3

</pre>