Installing, Migrating & Upgrading Redmine with LDAP on Ubuntu

     

Preamble

Note for CentOS users: please refer to my more recent guide, Redmine on CentOS 7

This article will guide you through the installation, migration and upgrading of a Redmine instance on Ubuntu Server 13.10. The article’ll also explain how to switch from an SQLite database backend to PostgreSQL. For authentication we’ll be using LDAP. The LDAP backend in our case is Active Directory, but it should work with any LDAP-compliant server. The procedure should be fairly similar on other releases or distros, too.

There are several commands where I use dummy values (server URLs, file system paths, LDAP environment etc.), so please check every one of them and update them according to your setup.

Clean install

This section assumes that you don’t have any existing data that needs to be taken care of. We’ll stick with the PostgreSQL database, for others check out the official installation guide.

Repositories

If you want Git integration, you gotta mount the NFS exports provided by the Git server. Install the required tools:

apt-get install nfs-common

Create a directory for accessing the repos:

mkdir -p /opt/git

Then add the following to /etc/fstab (update the Git server address and export name):

git.foobar.local:/git /opt/git nfs4 auto 0 0

Then mount with mount -a. If everything’s fine, the remote Git repos will be available under /opt/git. As a last step, make sure Redmine can actually browse the repos so install the required binaries:

apt-get install git

Database

Install the PostgreSQL database server and the development files, too, so that the corresponding Ruby gems can also be built:

apt-get install postgresql libpq-dev

Now switch to the postgres user and enter the PostgreSQL command prompt:

su postgres
psql

Within this prompt, create the redmine user and the production (redmine) and test (redmine_test) databases. Also make the redmine user the owner of these 2 databases (replace the *** password with whatever you want):

CREATE ROLE redmine LOGIN ENCRYPTED PASSWORD '***' NOINHERIT VALID UNTIL 'infinity';
CREATE DATABASE redmine WITH ENCODING='UTF8' OWNER=redmine;
CREATE DATABASE redmine_test WITH ENCODING='UTF8' OWNER=redmine;

You can verify the result with list, and if it’s OK exit with quit.

If you want to manage the databases remotely, open /etc/postgresql/9.1/main/postgresql.conf, uncomment the listen_addresses line and set it to ‘‘*, i.e.:

listen_addresses = '*'

Additionally, add the following to /etc/postgresql/9.1/main/pg_hba.conf (modify the subnets accordingly):

host all all 192.168.0.0/24 md5

Redmine

Download the tar.gz release, extract it, then make it easily accessible via symlink:

wget https://www.redmine.org/releases/redmine-2.4.0.tar.gz
tar xf redmine-2.4.0.tar.gz -C /opt
cd /opt
ln -s redmine-2.4.0 redmine

Create the database configuration file:

touch /opt/redmine/config/database.yml

Then configure it to use our shiny new PostgreSQL instance (replace the dummy passwords):

test:
  adapter: postgresql
  database: redmine_test
  host: localhost
  username: redmine
  password: "***"

production:
  adapter: postgresql
  database: redmine
  host: localhost
  username: redmine
  password: "***"

Now install Ruby. You can use both 1.8 or 1.9. The Apache module which will be installed later depends on 1.8, so if you install 1.9 here, you’ll have both 1.8 and 1.9 installed which is a bit redundant, but this way you can skip a Ruby upgrade for Redmine later, and once the Apache module’s also upgraded to 1.9 you can easily uninstall 1.8, which is probably less maintenance work than handling and debugging a Ruby version bump for Redmine itself.

You’ll also need the Ruby gems, and for gem installation to work you’ll need make as well. So the installation procedure for Ruby 1.8 is:

apt-get install ruby1.8 ruby1.8-dev rubygems make

For 1.9 (1.9 bundles rubygems already):

apt-get install ruby ruby-dev make

Additionally, if you want to have Gantt chart generation:

apt-get install imagemagick libmagickcore-dev libmagickwand-dev

Certain gems may fail at documentation generation, so let’s just save some disk space and installation time and disable it altogether:

echo 'gem: --no-rdoc --no-ri' > ~/.gemrc

Now install the bundler gem which Redmine uses for setting up the environment, then install all the remaining stuff with bundler (if you want Gantt support, remove the rmagick word):

gem install bundler
cd /opt/redmine
bundle install --verbose --without development test rmagick

And some finishing touches (still under /opt/redmine):

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

Finally you can test your installation. Start the test server:

ruby script/rails server webrick -e production

Now you can reach your new server via HTTP on port 3000 with the usual admin/admin login.

Web server

Webrick is nice for testing purposes but for production you need something more robust. Install Apache and the Passenger module (a.k.a. mod_rails):

apt-get install apache2 libapache2-mod-passenger

Now create the redmine site and disable the default one:

touch /etc/apache2/sites-available/001-redmine.conf
cd /etc/apache2/sites-enabled
rm 000-default.conf
ln -s ../sites-available/001-redmine.conf .
ln -s /opt/redmine/public /var/www/redmine

Set up the Redmine site (001-redmine.conf):

<VirtualHost *:80>

    ServerAdmin [email protected]
    ServerName redmine.foobar.local

    DocumentRoot /var/www/redmine
    LogLevel warn
    ErrorLog /opt/redmine/log/error.log
    CustomLog /opt/redmine/log/access.log combined

    <Directory /var/www/redmine>
        Options FollowSymLinks
        AllowOverride None
        Order deny,allow
        Allow from all
        RailsEnv production
        RailsBaseURI /redmine
        PassengerResolveSymlinksInDocumentRoot on
    </Directory>

</VirtualHost>

Now restart the Apache service and then you can test your Redmine instance on port 80:

service apache2 restart

Authentication

Here we’ll use the ldap_browser Domain User (it does not need to be Domain Admin!) account to query information from LDAP. Members of the Redmine Users security group (LDAP filter) will be allowed to log in to Redmine given they’re found under the OU=Users,DC=foobar,DC=local LDAP DN (Base DN).

Go to Administration / LDAP authentication and create a New authentication mode (make sure to update the LDAP environment and the password):

Attribute Value
Name foobar.local
Host dc1.foobar.local
Port 636
LDAPS checked
Account CN=ldap_browser,OU=Users,DC=foobar,DC=local
Password ***
Base DN OU=Users,DC=foobar,DC=local
LDAP filter (memberOf=CN=Redmine Users,OU=Groups,DC=foobar,DC=local)
Timeout (in seconds) 10
On-the-fly user creation checked
Login attribute sAMAccountName
Firstname attribute givenName
Lastname attribute sn
Email attribute mail

On-the-fly user creation may sound a bit confusing. It won’t touch your LDAP domain, all it does is create a local Redmine user that corresponds to the LDAP user.

Migration

In this section we’ll migrate an existing Redmine instance to a new server with possibly a newer Redmine version. We’ll also cover the case where the old instance is running SQLite and the new one’s using PostgreSQL. For database conversion we’ll use the old Redmine server or (preferably) an intermediate virtual server which can be removed later.

MySQL is not covered here. I’ve tried to perform a migration from SQLite to MySQL but it gave me internal server errors on random projects after converting with taps, so I do not recommend using it.

File export & import

Copy from the old server to the new one:

  • config/configuration.yml
  • files/*
  • plugins/*
  • public/themes/*

These locations may vary depending on compile-time options and/or settings so take a look around. Certain packages may put these files under:

  • /etc/redmine
  • /var/lib/redmine
  • /usr/share/redmine
  • /var/www/redmine

Update file permissions if needed. Additionally, review and update configuration.yml according to the new environment. The same applies to the settings available via the web interface under Administration.

If there are existing users with Internal authentication method, make sure not to delete them, just change their method to the LDAP one instead (assuming there’s a corresponding LDAP user).

Also make sure not to carry over config/settings.yml, it’s not for user settings.

Database export from SQLite 3

Install the SQLite 3 tools on the old server using SQLite:

apt-get install sqlite3

Go to the folder where your SQLite database resides and make a copy of it. If the Redmine server’s still running:

sqlite3 redmine.sqlite3

This will enter to the SQLite command line. Now type:

.backup /tmp/redmine_backup.sqlite3
.exit

Which will make sure there’s no corruption (i.e. no writes running in the background while you’re making the copy). If the server’s not running you don’t have to deal with this and just copy the file manually:

cp redmine.sqlite3 /tmp/redmine_backup.sqlite3

Now either on this or on an intermediate VM (preferably not on the final server to avoid bloat) install the Ruby tools. You need Ruby 1.9 because the taps gem won’t install with 1.8. Also install the database development files:

apt-get install ruby ruby-dev make libsqlite3-dev libpq-dev

Disable gem documentation generation:

echo 'gem: --no-rdoc --no-ri' > ~/.gemrc

Now install various gems. The 1.5.2 version of the rack gem is breaking database conversion so stick with 1.4:

gem install rack -v 1.4.5
gem install sqlite3 pg taps

Install the PostgreSQL server:

apt-get install postgresql

Now switch to the postgres user and enter the PostgreSQL command prompt:

su postgres
psql

Create a user and a repo for redmine (update the password):

CREATE ROLE redmine LOGIN ENCRYPTED PASSWORD '***' NOINHERIT VALID UNTIL 'infinity';
CREATE DATABASE redmine WITH ENCODING='UTF8' OWNER=redmine;
q

Start a taps server which publishes the SQLite database:

taps server sqlite:///tmp/redmine_backup.sqlite3 tmpuser tmppass

Start another taps server which pulls this SQLite database into a PostgreSQL one (update the redmine user’s password):

taps pull postgres://redmine:***@localhost/redmine http://tmpuser:tmppass@localhost:5000

Once finished, switch to the postgres user and create a database dump:

su postgres
pg_dump redmine > /tmp/redmine_backup.pgsql

Database export from PostgreSQL

This is the same as the ending steps of the SQLite export, i.e. switch to the postgres user and create a database dump:

su postgres
pg_dump redmine > /tmp/redmine_backup.pgsql

Database import

You have to do the same as with a clean install, except before the rake generate_secret_token step perform a database import:

su postgres
psql redmine < /tmp/redmine_backup.pgsql

Now continue with the installation, but make sure to skip the database initialization step (RAILS_ENV=production rake redmine:load_default_data) and before running the web server (either Webrick or Apache), perform some additional cleanup, too:

rake redmine:plugins:migrate RAILS_ENV=production
rake tmp:cache:clear
rake tmp:sessions:clear

Upgrade

Set up the environmental variables to make your life easier:

export OLD_REDMINE=2.4.0
export NEW_REDMINE=2.4.1

Stop the web server to avoid any new data to be written:

service apache2 stop

Download the new release and set up file structure:

wget https://www.redmine.org/releases/redmine-${NEW_REDMINE}.tar.gz
tar xf redmine-${NEW_REDMINE}.tar.gz -C /opt
cd /opt
ln -sf redmine-${NEW_REDMINE} redmine

Then copy the old config to the new place:

cp redmine-${OLD_REDMINE}/config/configuration.yml redmine/config
cp redmine-${OLD_REDMINE}/config/database.yml redmine/config
cp -R redmine-${OLD_REDMINE}/files redmine
cp -R redmine-${OLD_REDMINE}/plugins redmine
cp -R redmine-${OLD_REDMINE}/log redmine

Additionally, manually copy any downloaded themes from public/themes.

Now perform some Redmine upgrade procedures:

cd /opt/redmine
bundle install --verbose --without development test rmagick
rake generate_secret_token
RAILS_ENV=production rake db:migrate
rake tmp:cache:clear
rake tmp:sessions:clear

Fix file permissions:

chown -R www-data:www-data /opt/redmine-${NEW_REDMINE}

Then restart the web server:

service apache2 start

Tasks

Resetting the admin password

If you lose access to the admin account but you can still access PostgreSQL:

su postgres
psql

Then in the SQL prompt:

connect redmine
UPDATE users SET hashed_password='353e8061f2befecb6818ba0c034c632fb0bcae1b' WHERE login='admin';
UPDATE users SET salt='' WHERE login='admin';

Where hashed_password is sha1(sha1(password)), so this hash will set the admin password to password. This procedure clears the salt so make sure to change the password again via the web UI once logged in, which regenerates the salt.

Renaming a project

TODO