Redmine

h1. HowTo Install Redmine 3.0.x on Ubuntu 14.04 with Apache2, Phusion Passenger, MySQL, Subversion and Git (Gitolite)

{{toc}}

Based on "Debian HowTo":http://www.redmine.org/projects/redmine/wiki/HowTo_Install_Redmine_2_integrated_with_Gitolite_2_on_Debian_Wheezy_with_Apache_and_Phusion_Passenger from "André Domarques":http://www.redmine.org/users/85560

h2. Installing dependencies

<pre>

sudo apt-get update && sudo apt-get upgrade -y

sudo apt-get install apache2 php5 libapache2-mod-php5 mysql-server php5-mysql libapache2-mod-perl2 libcurl4-openssl-dev libssl-dev apache2-prefork-dev libapr1-dev libaprutil1-dev libmysqlclient-dev libmagickcore-dev libmagickwand-dev curl git-core gitolite patch build-essential bison zlib1g-dev libssl-dev libxml2-dev libxml2-dev sqlite3 libsqlite3-dev autotools-dev libxslt1-dev libyaml-0-2 autoconf automake libreadline6-dev libyaml-dev libtool imagemagick apache2-utils ssh zip libicu-dev libssh2-1 libssh2-1-dev cmake libgpg-error-dev subversion libapache2-svn

</pre>

I don't know if every package needed, but it works.

h2. Configure Subversion

<pre>

sudo mkdir -p /var/lib/svn

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

sudo a2enmod dav_svn

</pre>

Open config file

<pre>

sudo nano /etc/apache2/mods-enabled/dav_svn.conf

</pre>

Uncomment following lines

<pre>

<Location /svn>

	DAV svn

	SVNParentPath /var/lib/svn

    AuthType Basic

    AuthName "My repository"

    AuthUserFile /etc/apache2/dav_svn.passwd

	AuthzSVNAccessFile /etc/apache2/dav_svn.authz

	<LimitExcept GET PROFIND OPTIONS REPORT>

	Require valid-user

	</LimitExcept>

</Location>

</pre>

<pre>

sudo a2enmod authz_svn

</pre>

Add the redmine user for reading from repository

<pre>

sudo htpasswd -c /etc/apache2/dav_svn.passwd redmine

sudo service apache2 restart

</pre>

Create the repository

<pre>

sudo svnadmin create --fs-type fsfs /var/lib/svn/my_repository

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

</pre>

Open file for configuration of repository access

<pre>

sudo nano /etc/apache2/dav_svn.authz

</pre>

Add access rights for redmine to the repository in the config file

<pre>

[my_repository:/]

redmine = r

</pre>

h2. Installing Ruby

<pre>

sudo apt-get install software-properties-common

sudo add-apt-repository ppa:brightbox/ruby-ng

sudo apt-get update

sudo apt-get -y install ruby2.1 ruby-switch ruby2.1-dev ri2.1 libruby2.1 libssl-dev zlib1g-dev

sudo ruby-switch --set ruby2.1

sudo ruby-switch --set ruby2.1

</pre>

h2. Users and SSH keys

h3. Users

Create an user for Redmine (redmine) and another for Gitolite (git):

<pre>

sudo adduser --system --shell /bin/bash --gecos 'Git Administrator' --group --disabled-password --home /opt/gitolite git

sudo adduser --system --shell /bin/bash --gecos 'Redmine Administrator' --group --disabled-password --home /opt/redmine redmine

</pre>

Generate a ssh-key for redmine user. This user will be used as admin of Gitolite. The name of key should be redmine_gitolite_admin_id_rsa.

<pre>

sudo su - redmine

ssh-keygen -t rsa -N '' -f ~/.ssh/redmine_gitolite_admin_id_rsa

exit

</pre>

h3. Configuring Gitolite

<pre>sudo dpkg-reconfigure gitolite</pre>

Type data bellow:

* user: git

* repos path: /opt/gitolite

* admin ssh-key: /opt/redmine/.ssh/redmine_gitolite_admin_id_rsa.pub

h3. Visudo configuration

<pre>sudo visudo</pre>

Add the following lines:

<pre>

# temp - *REMOVE* after installation

redmine    ALL=(ALL)      NOPASSWD:ALL

# redmine gitolite integration

redmine    ALL=(git)      NOPASSWD:ALL

git        ALL=(redmine)  NOPASSWD:ALL

</pre>

Note that redmine user will be able to run root commands, but this is just to simplify the next steps. REMOVE this line after installation.

h2. Installing of Redmine

h3. Prerequist

<pre>

sudo su - redmine

gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3

curl -sSL https://get.rvm.io | bash -s stable

exit

</pre>

Its necessary to logout and login again

<pre>

sudo su - redmine

rvm install 2.1.4

exit

</pre>

h3. Redmine

Exampe for version 3.0.4, change the version number for other releases

<pre>

sudo su - redmine

wget http://www.redmine.org/releases/redmine-3.0.4.tar.gz

tar zxf redmine-3.0.4.tar.gz

rm redmine-3.0.4.tar.gz

ln -s /opt/redmine/redmine-3.0.4 redmine

exit

</pre>

h3. MySQL

<pre>

sudo mysql -u root -p

</pre>

Execute following lines to MySQL

<pre>

CREATE DATABASE redmine character SET utf8;

CREATE user 'redmine'@'localhost' IDENTIFIED BY 'my_password';

GRANT ALL privileges ON redmine.* TO 'redmine'@'localhost';

exit

</pre>

Configure Redmine database connection

<pre>

sudo su - redmine

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

</pre>

Open database config file

<pre>

sudo nano redmine/config/database.yml

</pre>

Change the username and the password in the config file

<pre>

database.yml:

production:

 adapter: mysql2

 database: redmine

 host: localhost

 username: redmine

 password: my_password

 encoding: utf8

</pre>

h3. Configuration

<pre>

gem install bundler

cd redmine/

bundle install --without development test postgresql sqlite

rake generate_secret_token

RAILS_ENV=production rake db:migrate 

RAILS_ENV=production rake redmine:load_default_data

exit

</pre>

h2. Redmine Git Hosting

h3. Download

Exampe for version 1.1.1, change the version number for other releases

<pre>

sudo su - redmine

cd /opt/redmine/redmine/plugins

git clone https://github.com/jbox-web/redmine_bootstrap_kit.git

git clone https://github.com/jbox-web/redmine_git_hosting.git

cd redmine_git_hosting

git checkout 1.1.1

</pre>

h3. Configure

<pre>

ln -s /opt/redmine/.ssh/redmine_gitolite_admin_id_rsa /opt/redmine/redmine/plugins/redmine_git_hosting/ssh_keys/redmine_gitolite_admin_id_rsa

ln -s /opt/redmine/.ssh/redmine_gitolite_admin_id_rsa.pub /opt/redmine/redmine/plugins/redmine_git_hosting/ssh_keys/redmine_gitolite_admin_id_rsa.pub

ln -s /opt/redmine/.ssh/redmine_gitolite_admin_id_rsa /opt/redmine/.ssh/id_rsa

ln -s /opt/redmine/.ssh/redmine_gitolite_admin_id_rsa.pub /opt/redmine/.ssh/id_rsa.pub

</pre>

h3. Configure GL_GITCONFIG_KEYS

This version now use some hooks that, by default on gitolite v2, will be blocked by the var GL_GITCONFIG_KEYS. On gitolite v3, this var is named GIT_CONFIG_KEYS.

<pre>

sudo su - git

sed -i 's/$GL_GITCONFIG_KEYS = ""/$GL_GITCONFIG_KEYS = ".*"/g' /opt/gitolite/.gitolite.rc

exit

</pre>

h3. Configure Automatic Repository Initialization

To configure the new feature "Automatic Repository Initialization" (optional), is necessary to customize the gitolite.conf file.

<pre>

cd ~

git clone git@localhost:gitolite-admin.git

cd gitolite-admin

</pre>

Open gitolite config file

<pre>

nano conf/gitolite.conf

</pre>

Add following config

<pre>

repo    @all

	RW+    = admin

</pre>

<pre>

git config --global user.email "you@example.com"

git config --global user.name "Your Name"

git commit -m 'Automatic Repository Initialization' conf/gitolite.conf

git push

cd ~

rm -rf gitolite-admin

</pre>

Remember that this repository will be managed by redmine and their plugin.

h3. Installation

<pre>

cd redmine

bundle install --without development test postgresql sqlite

RAILS_ENV=production rake redmine:plugins:migrate

RAILS_ENV=production rake redmine_git_hosting:update_repositories

RAILS_ENV=production rake redmine_git_hosting:fetch_changesets

RAILS_ENV=production rake redmine_git_hosting:restore_default_settings

RAILS_ENV=production rake redmine_git_hosting:install_hook_files

RAILS_ENV=production rake redmine_git_hosting:install_hook_parameters

RAILS_ENV=production rake redmine_git_hosting:install_gitolite_hooks

exit

</pre>

h2. Remove redmine root access

<pre>sudo visudo</pre>

_REMOVE_ following entry

<pre>

# temp - *REMOVE* after installation

redmine    ALL=(ALL)      NOPASSWD:ALL

</pre>

h2. Installing Phusion Passenger

h3. Add repository

Add repository for Phusion Passenger

<pre>

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 561F9B9CAC40B2F7

sudo apt-get install apt-transport-https ca-certificates

</pre>

Open repository config file

<pre>

sudo nano /etc/apt/sources.list.d/passenger.list

</pre>

Add following repository source

<pre>

deb https://oss-binaries.phusionpassenger.com/apt/passenger trusty main

</pre>

<pre>

sudo chown root: /etc/apt/sources.list.d/passenger.list

sudo chmod 600 /etc/apt/sources.list.d/passenger.list

</pre>

h3. Installing

<pre>

sudo apt-get update

sudo apt-get install libapache2-mod-passenger

</pre>

h3. Configuration

Open passenger config file

<pre>

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

</pre>

Add following line to passenger config file

<pre>

PassengerUserSwitching on

PassengerUser redmine

PassengerGroup redmine

</pre>

Open apache2 config file

<pre>

sudo nano /etc/apache2/sites-available/000-default.conf

</pre>

Add following part to apache2 config file

<pre>

<Directory /var/www/html/redmine>

    RailsBaseURI /redmine

    PassengerResolveSymlinksInDocumentRoot on

</Directory>

</pre>

<pre>

sudo a2enmod passenger

sudo ln -s /opt/redmine/redmine/public/ /var/www/html/redmine

sudo service apache2 restart

</pre>

h2. Start Redmine

Remine should now available at your host

<pre>

http://your_ip_or_fqdn/redmine

</pre>

Login data:

Username: admin

Password: admin

h2. Redmine configuration

Configure the Redmine default URL (*important*):

Administration > Settings > General

http://your_ip_or_fqdn/redmine/settings?tab=general

This is set, by default, to localhost:3000, change it to your IP or FQDN. your_ip_or_fqdn/redmine/

h3. Set the available repositories

Administration > Settings > Repositories

http://your_ip_or_fqdn/redmine/settings?tab=repositories

Uncheck what you don't have installed on your system. Just to avoid unnecessary log message.

Enable xitolite for using the Redmine Git Hosting plugin

h2. Redmine Git Hosting Plugin

h3. First of all, check the configuration

Administration > Redmine Git Hosting Plugin > Config Test

http://your_ip_or_fqdn/redmine/settings/plugin/redmine_git_hosting?tab=gitolite_config_test

Ensure if all settings are correct (users, paths, versions etc.). 

h3. Set your IP or FQDN to SSH, HTTP and/or HTTPS

Administration > Redmine Git Hosting Plugin > Access

http://your_ip_or_fqdn/redmine/settings/plugin/redmine_git_hosting?tab=gitolite_config_access

Administration > Redmine Git Hosting Plugin > Hooks

http://your_ip_or_fqdn/redmine/settings/plugin/redmine_git_hosting?tab=gitolite_config_hooks

Hooks: http://your_ip_or_fqdn/redmine

Those settings will be also used on git operations (clone, pull, push etc.).

h2. e-Mail configuration

Example for smtp and encryption

Open redmine config file

<pre>

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

</pre>

Add following to redmine config file

<pre>

# Outgoing email settings

production:

  email_delivery:

    delivery_method: :smtp

    smtp_settings:

      enable_starttls_auto: true

      address: smtp.host.com

      port: 587

      domain: host.com

      authentication: :login

      user_name: myname

      password: mypassword

</pre>

You can check the e-Mail config in web interface with testmail function

h2. Autoupdate Subversion repository view

In the project archive settings over web interface its needed to enable the web service for project archives and generate a api key

The following cronjob updates redmine to current subversion changesets every 15 minutes

<pre>

sudo crontab -e

</pre>

Add the cronjob

<pre>

*/15 *    * * * curl "http://yourhost/redmine/sys/fetch_changesets?key=APIKEY" > /dev/null

</pre>

If your hosting does not offer cron job configuration then you can use external services like these:

https://www.easycron.com.

h2. SSL, HTTPS and Smart-HTTPS (Git)

h3. Own certificate

Create Private Key

<pre>

sudo mkdir /etc/apache2/ssl

cd /etc/apache2/ssl

sudo openssl genrsa -des3 -out server.key 1024

</pre>

Create CSR (Certificate Signing Request)

<pre>

cd /etc/apache2/ssl

sudo openssl req -new -key server.key -out server.csr

</pre>

Remove of the passphrase vom private key

<pre>

cd /etc/apache2/ssl

sudo cp server.key server.key.org

sudo openssl rsa -in server.key.org -out server.key

</pre>

Generate selfsigned certificate

<pre>

cd /etc/apache2/ssl

sudo openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

</pre>

h3. Configuration of apache2

Enable SSL module

<pre>sudo a2enmod ssl</pre>

Modification of apache2 configuration

<pre>sudo nano /etc/apache2/sites-available/default-ssl.conf</pre>

Following config is needed:

<pre>

<IfModule mod_ssl.c>

        ...

        <VirtualHost _default_:443>

                ServerAdmin webmaster@localhost

                DocumentRoot /var/www/html

                ErrorLog ${APACHE_LOG_DIR}/error.log

                CustomLog ${APACHE_LOG_DIR}/access.log combined

                SSLEngine on

                SSLCertificateFile      /etc/apache2/ssl/server.crt

                SSLCertificateKeyFile /etc/apache2/ssl/server.key

                <Directory /var/www/html/redmine>

                        RailsBaseURI /redmine

                        PassengerResolveSymlinksInDocumentRoot on

                </Directory>

        </VirtualHost>

        ...

    </IfModule>

</pre>

Activate the new configuration

<pre>sudo a2ensite default-ssl</pre>

h3. Smart-HTTPS client (Git)

For the client is needed to disable certificate verification. With Git bash:

<pre>git config --global http.sslverify false</pre>

*Caution:* This can be a security risk at access to foreign repositorys!

h1. Troubleshooting

h2. Logs

If you have some trouble during the installation, you can check the following files:

* /opt/gitolite/.gitolite/logs/gitolite-`date +%Y\-%m`.log

* /opt/redmine/log/git_hosting.log

* /var/log/apache2/error.log

If you use multitail:

multitail /opt/gitolite/.gitolite/logs/gitolite-`date +%Y\-%m`.log /opt/redmine/log/git_hosting.log /var/log/apache2/error.log