Redmine Installation Instructions

On the following page I will explain how to install Redmine together with the required packages on a virtual machine running on a normal GSI linux computer.

Prerequisites

• Root access on the host computer
• virtualization support on the host computer
• virtual machine image with basic Debian Wheezy system

Install virtualization support on host computer

For the installation of the virtualization support please check the excellent information provided by Victor Penso. The instructions and the scripts can be found at github. There are also instructions how to get a virtual machine image at GSI.

Adapt the virtual Debian Wheezy image

The image are missing some important features which has to be installed before you can install Redmine using the cookbook. Everything can be installed using apt.

• lsb-release : without the package chef-solo will not work
• ca-certificates : allow to install the GSI specific certificates
• ruby-dev : without the package the mysql installation fails, because it is using gems
• GSI related certificates : Needed to connect to the GSI subversion repository.
• locate ?
• unzip ?

Before running apt one must copy the GSI related certificates to the correct position in the file system of the vm. In the directory with the instance of the vm use the following command to copy the required files from the host system to the correct location of the vm

vm put /usr/local/share/ca-certificates/dfn_pca_global_g01.crt /usr/local/share/ca-certificates/  
vm put /usr/local/share/ca-certificates/gsi_ca_02.crt /usr/local/share/ca-certificates/

After you copied the files login to the machine and run apt to install all the additional packages.

sudo apt-get install lsb-release ca-certificates ruby-dev <everything else>

Now you have an image which can be used as base for the redmine installation.

Create a new instance of the virtual image

vm clone <your image> lxdev01

After some time the machine is provisioned and booted so you can login

vm login

If everything looks okay log out again.

Install Redmine

Copy the required cookbooks to the directory holding the instance of the virtual machine

vm config add cookbook <name>

Copy and edit or create the file with the instructions for chef-solo and store in the directory of the instance of the virtual machine. An example of the file is shown below.

{
  "run_list": [
    "recipe[apt]",
    "recipe[redmine]"
  ],
  "apt": {
    "packages": [
      "vim",
      "less",
      "joe",
      "apt-show-versions",
      "lynx",
      "unzip",
      "ruby-dev"
    ]
  },
  "redmine": {
    "databases": {
      "production": {
        "password": "my_secret_password"
      }
    }
  },
  "mysql": {
    "server_root_password": "another_secret_password"
  }
}

Now you can start the installation using chef-solo

vm config solo

which will copy the information to the virtual machine and start chef-solo. The installation will crash at some point (installing libaprutil). Rerun the configuration again and the installation will run till the end. After chef-solo has finished successfully one has to create the correct rules for the port forwarding from the host machine to the virtual machine. This is again done by some of Victors fantastic scripting commands.

vm forward add <instance_name>:port <port of host computer>

e.g.

vm forward add lxdev02:80 80
vm forward add lxdev02:443 443

Now you can login to Redmine for the first time. Use your favorite browser to navigate to the following URL

.gsi.de

If everything works you will be redirected to the https version of Redmine.

Congratulation. You have now a running Redmine installation. Now we come to the necessary configuration of Redmine.

Redmine Configuration

Change the default admin information

Now you should login and immediately change the admin password. Click on Sign In in the upper left corner of the web page and login with the default combination admin/admin. Click on Administration and Users and choose the admin user to change the password, the mail address and other things. After changing the items don't forget to save. To test if everything works log out and in again.

Change the general settings

Chose Administration, Settings, General and provide a good Name for the Redmine instance and write a nice welcome text which will be shown on the first page. Also set the host name and choose if you prefer http or https. Should make no difference since we redirect http to https anyway. Save the settings.

Sending E-Mail

TODO: Create a template which creates the needed file during the installation procedure.

To be able to send emails one has to set the correct information about the mail transport agent which should be used. Copy the example file, create a symbolic link and edit the file

sudo cp /usr/local/share/redmine/current/config/configuration.yml.example /usr/local/share/redmine/shared/config/configuration.yml
sudo ln -s /usr/local/share/redmine/shared/config/configuration.yml /usr/local/share/redmine/current/config/configuration.yml
joe /usr/local/share/redmine/shared/config/configuration.yml

In this file one finds several examples for different mail configurations. To send email at GSI one can use the smtp server at GSI. The settings are shown below.

default:
  # Outgoing emails configuration (see examples above)
  email_delivery:
    delivery_method: :smtp
    smtp_settings:
      address: "smtp.gsi.de"
      port: 25

sudo service apache2 restart

Save the file and restart apache that the changes take effect. Now log in as admin and choose Administration, Settings, Email notification to change the email settings. Choose a good name as sender address. Beside that chose whatever seems appropriate for you. In the text field for the email footer exchange hostname by the name of the machine. Save the settings and the test the mail by clicking on Send a test mail in the lower right corner of the page. If you receive the mail everything is okay.

Enable the LDAP authentication

If you only want to authenticate against the GSI LDAP server, you only have to fill in the required information which are shown in the attached screenshot. Here it is only tested if the user has a GSI web account and if the given password is correct. If the user is authenticated automatically a new user in Redmine is created.

To do this please choose Administration, LDAP authentication. Since there is no LDAP defined click on new authentication mode and fill the form with help of the attached screenshot.

If you also want to check if the user is in a distinct group you have to patch Redmine and fill the form with the complete info given in the attached screenshot. Also the new lines Group DN and LDAP group filter have to be filled. The two lines mentioned above are only present in the patched version of Redmine.

To patch Redmine copy the attached patch in the redmine directory of the virtual machine. To test if the patch will work you can use the following git commands in the redmine directory (/usr/local/share/redmine/current/)

git apply --stat redmine_ldap_group_auth.patch
git apply --check redmine_ldap_group_auth.patch

To apply the patch use the following command

git am --signoff < redmine_ldap_group_auth.patch

Now you have to add the needed changes to the database. This is done with running the following command in the redmine directory.

sudo rake db:migrate RAILS_ENV=production

Now restart apache again and check if the two new lines show up on the web page for LDAP authentication.

sudo service apache2 restart

Please fill the complete form with the required information, log out and try to Sign In with your GSI web account. Don't use Register. If the authentication works you end in the registration form which you have to fill and save.

Install useful plugins

Redmine is extendable by an enormous amount of plugins. A list of available plugins can be found at Redmine webpage. Instructions about plugin installation is here.

In the following I will list a personal list of useful plugins and installation instructions if they differ from the normal installation procedure.

• Redmine Ldap Sync
• Code Review

Install and configure the Ldap Sync plugin

The info about the plugin is here

Navigate to the plugins directory (/usr/local/share/redmine/current/plugins), clone the git repository, do the installation and restart the web server.

cd /usr/local/share/redmine/current/plugins
sudo git clone https://github.com/thorin/redmine_ldap_sync.git
cd /usr/local/share/redmine/current/
sudo bundle install
sudo rake redmine:plugins:migrate RAILS_ENV=production
sudo chown -R www-data:www-data tmp/ldap_cache
sudo service apache2 restart

In the Administration section one should see now the LDAP synchronization entry.

The configuration is in the moment unclear. Here we have to understand how the Ldap connection is done in detail. TODO: Get the correct parameters for the Ldap sync

Install the Code Review plugin

The info about the plugin is here

Download the zip file, unzip it and do the installation procedure.

cd /usr/local/share/redmine/current/plugins
sudo wget https://bitbucket.org/haru_iida/redmine_code_review/downloads/redmine_code_review-0.6.2.zip
sudo unzip redmine_code_review-0.6.2.zip
cd /usr/local/share/redmine/current/
sudo rake redmine:plugins:migrate RAILS_ENV=production
sudo service apache2 restart

TODO: Configuration instructions

-- FlorianUhlig - 28 Jun 2013