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
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
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
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
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
deb http://www.backports.org/debian lenny-backports main contrib non-free
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!
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.)
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
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
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,
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
password to what was set to be MySQL user
... production: adapter: mysql database: redmine host: localhost username: redmine password: passwordusedforredmine encoding: utf8 ...
Create a “session store secret”:
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
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
Hit Ctrl+C to kill the test server.
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
the first place.
/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.
Then point your browser to
http://localhost/redmine. It should work
now! You can log in using the default credentials,
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.
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