Bookmark and Share

Setting up Redmine on Debian with Apache

I needed a versatile software project management application. It should include issue tracking system, resource tracker, wiki, etc.—all the non-code stuff that any nontrivial real-world project needs. Redmine seemed to be one of the better alternatives, so I decided to give it a try.

Installing Redmine on a stable Debian server (“lenny”) was not quite as easy as it usually is with Debian (apt-get install redmine). Even lenny-backports provided only version 0.9.4, which has plenty of known bugs, so I didn’t want to use it. The “stable package” philosophy of Debian doesn’t really work too well for this kind of new, fast-developing pieces of software. On the other hand, checking out latest sources from the Redmine repository is a bit extreme to my taste. So I decided to install the official 1.0.0 release candidate from rubyforge.org.

One advantage of installing the official release is that it includes the appropriate Rails version in its vendor directory. This is particularly welcome, since Redmine is quite picky about exact versions of Ruby, Rails, Rack, Rake… Not only the usual “X must be at least version Y”, but also that “Ruby 1.9 is not supported yet” and “Rack must be version 1.0.1 exactly”. Somewhat scary, huh?

What makes the installation challenging is not only how to get it work in the first place, but also how to prevent it from breaking when some Debian package gets updated (you do update your Debian frequently, do you?). Let’s see. Now that Rails comes with the official Redmine release, we still need:

  • Ruby 1.8.6 or 1.8.7. Lenny’s ruby1.8 is currently 1.8.7. Ok!
  • RubyGems 1.3.1 or higher. Lenny’s rubygems1.8 is only 1.2.0. Bad!
  • Rake 0.8.3 or higher. Lenny’s rake is only 0.8.1. Bad!
  • Rack 1.0.1. This is to be installed via RubyGems.

So it seems that we can only use the Ruby package from Debian lenny. All the other dependencies are too old to work with Redmine 1.0.0, and thus they need to be installed by other means. Perhaps lenny-backports could help us?

Considering the stability, now there are at least two ways the installation could break:

  • You install a newer version of Redmine without checking possibly changed requirements.

  • Debian updates Ruby1.8 from 1.8.7 to a newer one, and it wouldn’t work with Redmine 1.0.0. This is unlikely.

RubyGems needs to be 1.3.1 or higher, Rake 0.8.3 or higher, and Rack, which has to be exactly 1.0.1, is installed via RubyGems, which doesn’t install updates automatically. So I think we’re on relatively safe ground, stability-wise.

Setting up backports

Unless you haven’t already, set up backports by adding the following lines to /etc/apt/sources.list:

deb http://www.backports.org/debian lenny-backports main contrib non-free

and running

aptitude update

To get rid of the GPG error, run also

aptitude install debian-backports-keyring

Now you can install the backport packages by

aptitude -t lenny-backports (whatevertoinstall)

Packages from backports do not upgrade automatically by default. To enable automatic upgrading, the following entry in /etc/apt/preferences should be sufficient:

Package: *
Pin: release a=lenny-backports
Pin-Priority: 200

Now we’re ready to start installing the actual dependencies!

Installing dependencies

We need the above mentioned Ruby, RubyGems, Rake, and a couple of other packages to provide the MySQL and Apache connectivity for Redmine.

aptitude install ruby1.8 libmysql-ruby1.8 libopenssl-ruby1.8 mysql-server
aptitude install -t lenny-backports rubygems rake libapache2-mod-passenger

Rack is installed via the gem package manager, which was installed above:

 gem install rack -v=1.0.1

(Note that there are two dots—1.0.1, not 1.01. I screwed this up first, and DB structure creation didn’t work.)

Configuring MySQL

MySQL is reportedly more robust when using the InnoDB storage engine instead of the default MyISAM, so it’s good to switch now—although this is optional, for sure. Create a file /etc/mysql/conf.d/innodb.cnf and put the following in it:

[mysqld]
default-storage-engine = InnoDB

Restart MySQL:

/etc/init.d/mysql restart

Then we need to create MySQL user and database for Redmine to use. Launch MySQL command line client, using the root password that was set when mysql-server was installed:

mysql -u root -p

Create a database and user, both named redmine:

create database redmine character set utf8;
grant all on redmine.* to 'redmine' identified by 'somepasswordhere';
quit

Installing and configuring Redmine

Phew! Now we should have the platform in order. Time to set up Redmine itself.

Download the latest version from RubyForge (I took redmine-1.0.0.tar.gz) and unzip it to /usr/local/lib/ (or anywhere, really):

cd /usr/local/lib/
wget http://rubyforge.org/frs/download.php/71723/redmine-1.0.0.tar.gz
tar -xzvf redmine-1.0.0.tar.gz
rm redmine-1.0.0.tar.gz

Create config file to make Redmine aware of its database:

cd redmine-1.0.0/
cp config/database.yml.example config/database.yml
pico config/database.yml

Make it like something like this (just change username to redmine and password to what was set to be MySQL user redmine’s password):

...
production:
  adapter: mysql
  database: redmine
  host: localhost
  username: redmine
  password: passwordusedforredmine
  encoding: utf8
...

Create a “session store secret”:

rake generate_session_store

Create database structure:

RAILS_ENV=production rake db:migrate

Install default configuration data in the database:

RAILS_ENV=production rake redmine:load_default_data

Select the (default) language to be used; you’ll be able to change it later on.

Apache web server, which needs to be able to read Redmine web site directories, runs as user called www-data in Debian (unless you’re using the multi-user version apache2-mpm-itk, in which case you’ll need to adjust appropriately here and in the following configuration section). So let’s set up appropriate permissions:

chown -R www-data:www-data files log tmp public/plugin_assets 
chmod -R 755 files log tmp public/plugin_assets

Update 31.8.2010: While the above permissions may work, I did run into an issue later on: apparently Phusion Passenger will run as the user who owns the rails app root directory—not as the www-data user even though Apache does—and if the owner of the directory is root, then Passenger runs as nobody. So a quick and dirty but perfectly working solution in case of permission problems is to make the whole redmine tree owned by www-data (or by some actual user):

chown -R www-data:www-data redmine-1.0.0

Now it’s good to check that the basic installation works, using the built-in Ruby WEBrick server temporarily:

ruby script/server webrick -e production

Point your browser to http://localhost:3000/. If you see the welcome page (an emptish home screen), everything is well so far. If you don’t see it, it’s better to debug now before proceeding to connect Redmine with Apache.

Hit Ctrl+C to kill the test server.

Configuring Apache

Thanks to Phusion Passenger (the libapache2-mod-passenger package that was installed above), this step is a breeze. I had luck with making a simple symbolic link to point from default www directory to Redmine’s public directory:

ln -s /usr/local/lib/redmine-1.0.0/public/ /var/www/redmine

Alternatively you could install Redmine directly under /var/www/ in the first place.

Then edit /etc/apache2/httpd.conf, add the following lines:

RailsEnv production
RailsBaseURI /redmine

Or, if you’re using virtual hosts, put those under the appropriate vhost setup so as not to unduly pollute the environment variables of other vhosts.

Restart Apache:

/etc/init.d/apache2 restart

Then point your browser to http://localhost/redmine. It should work now! You can log in using the default credentials, admin / admin, and adjust settings there.

Further to do

After getting Redmine to run somehow, there’s still stuff to do before you have a really working setup. For example:

  • Set up e-mail (SMTP) configuration.
  • Set up backups.
  • Set up logger configuration.
  • Link your (svn) repositories with Redmine.
  • etc.

There are plenty of links and tutorials for these in the RedmineInstall and Redmine wiki, FAQ and HowTo pages.

Especially the web server -related stuff depends on how Apache has been set up (or if you’re using some other httpd, then it’s another thing of course), are there other “sibling” sites, etc. If you’re in trouble, please consult (and try the alternative solutions provided by) the following sites, from which this article was extracted:

One more thing: do yourself a favor and check out Redmine Backlogs plugin. It’s awesome.

Last modified: 2010-09-02 15:20 +0300

blog comments powered by Disqus