Installing and customizing Redmine

(For more resources related to this topic, see here.)

Installing Redmine from the package

This guide can also be used to install Redmine on Debian. Ubuntu and Debian are very much alike so the installation procedure should not differ much. Still some things may differ.

Assuming you have already installed Ubuntu Server 12.04 LTS (or a more recent version). If not, please do it! Assuming also that this is a clean installation, so we will need to install, Apache, MySQL, and so on, all software needed to run Redmine. If some software is already installed it's not a problem as it is still safe to execute the commands given. The Ubuntu (and Debian) package manager is smart enough to skip already installed software.

Installing Redmine and MySQL server

Now let's execute the following command in the console:

$ sudo apt-get install redmine redmine-mysql mysql-server

Instead of redmine-mysql and mysql-server, you can use redmine-pgsql and postgresql or redmine-sqlite and sqlite3 here. However, remember that neither PostgreSQL nor SQLite3 is reviewed in this topic.

This command will install Redmine and MySQL as well as many dependency packages including Ruby and Rails. Before doing this, the Apt-Get package manager will ask you to confirm:

On the screen, type y and press Enter.

Configuring MySQL server package

After this it will download all the packages and start the installation process. Soon you will get the screen:

This screen asks you to enter a new password for the MySQL superuser. The same password will be used later to set up the Redmine database. After entering the password press Tab to switch to the Ok button and then press Enter.

You will be redirected to the password confirmation screen. Enter the same password again, press Tab (to move to the Ok button) and then press Enter.

After that it will take some time to install packages. In particular, it will install MySQL server and, when ready, initiate Redmine configuration.

Configuring Redmine package

The Debian/Ubuntu Redmine package supports many instances of Redmine. Several instances, for example, can be used to run Redmine in "production" and "development" modes at the same time (two instances for example, at different ports). The configurator of the package, however, will ask you to configure only one "default" instance.

On this screen the configurator suggests its assistance in creating and configuring the database for Redmine. Unless you are willing to configure the database by yourself just press Enter here.

The next screen, which appears immediately, asks you to select the database backend. It has nothing to do with database servers. This screen configures the Redmine database client. As we selected MySQL at command line just press Enter. And here comes the screen, which has already been mentioned:

Enter here the MySQL superuser password which you specified before. This password will be used to create, configure and populate the Redmine database. When finished press Tab to switch to the Ok button and press Enter.

Now the final screen of the Redmine database configuration comes:

The password, what this screen asks, will be used by Redmine to access its database. It is unlikely that this password will be used elsewhere, moreover, it should not be used elsewhere! So this password should be as complex as possible. Therefore it is, perhaps, better to just press Enter here and let the configurator generate the password for you.

You may also need to specify this password in Apache configuration files for advanced SCM integration.

After this screen the Redmine package configurator will perform some finalizing work and return to the shell prompt.

That's it! Redmine has been installed and configured and is ready to run. But the system is not yet ready to run Redmine. We need a web server to do this. As a web server we will use Apache. Besides Apache, we need something to run a Ruby application and this is going to be the Passenger module for Apache.

Installing Apache and Passenger

So let's now install Apache and Passenger:

$ sudo apt-get install apache2 libapache2-mod-passenger

As before you will be asked to press Enter. After this the package manager will download the specified packages and their dependencies, will install them and start Apache:

If everything has gone well, you should see [ OK ] to the right from Starting ... and Reloading ... messages, as seen on the screenshot. You may also get the warning you see on the screenshot, but do not worry, it just means you need to set Apache's ServerName property to a proper value.

Connecting Redmine and Apache

But, wait, where is Redmine? Right now Redmine is not connected to Apache. Unfortunately, despite the power of Debian package management software this part should be configured manually. Luckily it's not so complex: the Debian Redmine package contains sample configuration files for Redmine under /usr/ share/doc/redmine/examples directory. In this directory you will find sample configurations for Apache and FastCGI or Passenger, Lighttpd, Nginx and Thin. In this directory we have two sample files for Apache2 and Passenger: apache2- passenger-alias.conf and apache2-passenger-host.conf. The former should be used if you want to run Redmine under some URL path for example, The latter should be used if you want to run Redmine under subdomain or as the primary application on your domain.

Assuming that you have installed a clean Ubuntu (as I did) especially for Redmine, that is, that you want to use the server only for Redmine or for Redmine as the primary application. Let's copy apache2-passenger-host.conf to /etc/apache2/sites-available/ (the path for site configurations on Debian/Ubuntu).

$ sudo cp /usr/share/doc/redmine/examples/apache2-passenger-host.conf /

Actually this file contains configurations for two Redmine instances, "default" and "instance2", and on two different ports, 3000 and 3030. Let's clean it up to get a configuration for the "default" instance only and for the default port. We should get something like:

# These modules must be enabled : passenger
<VirtualHost *:80>
# ServerName
# this is the passenger config
RailsEnv production
# create a link in /var/lib/redmine/default/passenger to
PassengerAppRoot /var/lib/redmine/default/passenger
SetEnv X_DEBIAN_SITEID "default"
Alias "/plugin_assets/" /var/cache/redmine/default/
DocumentRoot /usr/share/redmine/public
<Directory "/usr/share/redmine/public">
Order allow,deny
Allow from all

I changed localhost:3000 to *:80, removed port numbers and the second <VirtualHost> configuration.

Before we proceed we need to do what is advised in the configuration file. To create symbolic link passenger in /var/lib/redmine/default pointing to /usr/share/redmine (the directory Redmine was installed into).

$ sudo ln -sf /usr/share/redmine /var/lib/redmine/default/passenger

Now we need to "apply" our new site. Remember we have copied apache2-passenger-host.conf to /etc/apache2/sites-available/? This directory stores available sites' configurations, as it comes from the name, and enabled sites configurations are stored in /etc/apache2/sites-enabled/. So we need to "move" our new configuration file into the latter directory. Let's do it in the correct Debian/Ubuntu way:

$ sudo a2ensite apache2-passenger-host.conf

The e2ensite script creates symbolic links in /etc/apache2/sites-enabled/ pointing to sites configuration files in /etc/apache2/sites-available/. The similar script e2dissite can be used to disable sites. So let's now disable the default site which comes with Apache in Debian/Ubuntu (the one displaying It works!):

$ sudo a2dissite default

Let's now reload Apache to activate the new configuration:

$ sudo service apache2 reload

Now when we load the site we get:

Congratulations! We have successfully installed Redmine. But still there are things we need to do before making a break for coffee and moving ahead.

Verifying and completing installation

Click on the Sign in link in the top-right corner to log in to our Redmine. Use admin as a login and as a password.

After you have signed in, click on the new item Administration on the top dark blue menu bar. Administration sections will appear on the right sidebar. Select the Information section.

The above screenshot shows the screen one should always check after installing Redmine! As you see it contains the checklist that should be used to verify the installation. Changing administrator account is a common procedure for any type of installation while installing RMagick is specific, that's why we came to this screen.

RMagick is Ruby interface for the ImageMagick image processing library. This library is used by Redmine for Gantt chart export. It can also be used by some third-party plugins.

So to install RMagick execute the following command:

$ sudo apt-get install ruby-rmagick

Now reload Apache again to apply:

$ sudo service apache2 reload

After Apache reloads, we get the green checkmark to the right from RMagick.

The only procedure left is changing the administrator account. To do this click on the Users link on the administration sidebar, open profile of the admin user (the only user available) and change login and password to some other values.


As you see this type of Redmine installation is quite easy and involves a few commands. Besides easiness, I believe, it has the following benefits:

  • The installed Redmine conforms to FHS (Filesystem Hierarchy Standard), that is, configuration files are located in /etc/redmine, Redmine itself in /usr/share/redmine, cache in /var/cache/redmine, logs in /var/log/ redmine, and so on. That is, any administrator, who is aware of FHS (even if he/she is not aware of Redmine), will be able to understand the Redmine file structure, and system tools, such as log analyzers, will be able to pick up and process Redmine files.

  • As Redmine was installed as a part of the Linux distribution, the system will be able to maintain it. Thus Redmine can be updated with the rest of the system and other system updates are unlikely to break Redmine.

Customizing Redmine

Personalization is the customization made by users for themselves using only the permissions they have. Installing plugins is the customization done by server administrators (don't confuse this with the Redmine administrator). In such cases we usually want to have our own look and feel (theme), to add custom content to different pages, and so on. During this customization phase users usually ask experts for help. Thus, sometimes they want to develop plugins to implement different ideas but plugins, actually, are not always needed. Also, during this phase users often customize Redmine by themselves and, usually, do this incorrectly. So, what the right way is to customize Redmine, what we can do without developing custom plugins, and so on, are the topics we will speak about now.

In the customization section we will cover the following topics:

  • Customizing with Textile

  • Customizing theme

  • Customizing with plugins

Customizing with Textile

I was formerly asked to create a custom plugin to improve the layout of the Redmine start page (available through the Home link) with buttons, links, sections, and other similar stuff. My answer was, you don't need a plugin to do that.

Textile is a very simplified HTML. Of course, it can't be used to create full-featured HTML pages, but for many things it can appear to be sufficient. However, to achieve the necessary results you, most likely, will need to use the most advanced Redmine Textile features. Also, similar to HTML, you can't just learn how to create a good look and feel—you can only get the idea. You will need to inject your own creativity to get what you need. Therefore, under this topic we will review some interesting customization examples, which should help you understand the technique.

Wiki pages as tabs in the project menu

The wiki Extensions plugin, created by Haruyuki Iida, allows adding wiki pages to the project menu as tabs (configured per project). You can find more information on this at .

Things we will discuss here will look tricky and, perhaps, you will ask, why should we prefer this technique over writing a plugin? The answer is, Textile formatting will survive the upgrade of Redmine, while a plugin, most likely, will need to be updated.

Using HTML code in wiki pages

Arlo Carreon created the wiki HTML Util plugin, which can be used to embed HTML, CSS, or JavaScript code directly into a wiki page. You can find more information at

Warnings and other boxes

Redmine core CSS classes can also be utilized to build information boxes in the wiki content, for example:

p(conflict). A warning message.
p(box). Rendered as a box.

This is shown as follows:

Icons for text

If you want to put an icon before a text, you can, for example:

You can insert "(icon icon-fav)a link with an icon": http://www. or even %(icon icon-checked).not a link%...

This Textile code will be rendered in the following way:

Here we use Redmine icon CSS classes and utilize the Textile SPAN element (using %).

Table-based layout

In modern web design everyone prefers building the page layout using DIVs and not old-style HTML tables. But in Textile we don't have enough control over DIVs. However, we can still use tables:

|{border:none}.eBook: %{color:#bbb}£18.99%|{border:none;padding:1em}.%
save 20%|{border:none}.!
|{border:none}.Print + free eBook + free PacktLib access to the
book: %{color:#bbb}£49.98%|{border:none;padding:1em}.%{fontsize:
save 44%|{border:none}.!

This tricky code produces the following result:

In this example we defined CSS styles for the table (table{border:none}.) and its cells (for example, |{border:none;padding:1em}.) and, again, utilized the HTML SPAN element (for example, %{color:#bbb}£49.98%).

Customizing themes

A common scenario of customization is when users first choose the theme for Redmine and then slightly modify it to fit their needs. As a result such users lose the possibility of upgrading the theme in future (as it now contains their changes).

Suppose we want to customize the Redmine Alternate theme. Instead of modifying the themes files under the public/themes/alternate directory, let's create a new theme based on this one. To do this let's create the packtpub subdirectory for our theme (this will be its name) in the public/themes directory. In the newly created directory create the stylesheets subdirectory and the application.css file in it.

Now add the following CSS code into this file:

@import url(../../../themes/alternate/stylesheets/application.css);
#top-menu { background-color: #040404; }
#header { background-color: #8db1c9; }
#main-menu li a { background-color: #404040; }

Here the first line loads CSS from the Alternate theme so we need to include only the difference into our customized one.

Customizing with plugins

The most advanced customization can be accomplished by writing a custom plugin. With a plugin you can customize literally anything in Redmine. Of course, to write a full-featured plugin you need to be familiar with Ruby, Rails, Redmine API, JavaScript, HTML, CSS, web development concept, and so on. But who said, that you need a full-featured plugin?

As you know, a plugin's files are kept in a separate directory named after the plugin and located in the plugins subdirectory of the Redmine root. This way when Redmine gets upgraded, the plugin's files remain untouched. On the other side, many users put their customizations into Redmine core files, which get overwritten on upgrade. So why not put customizations into a plugin?

The Redmine plugin API is quite flexible and you allows to: overwrite any core view file without touching the original one; to add custom content to different views; load additional CSS style sheets, and so on. Therefore, a plugin can be used as a tool for customization. In fact, you do not need to write any complicated Ruby code to do this—just use small code snippets to activate different plugins capabilities. That's what we will learn in this topic.

Of course, to be able to customize Redmine's look and feel you need to be familiar, at least, with HTML. Familiarity with CSS is optional but will be very useful.

Writing a simple plugin

To be able to make use of the plugin capabilities we need to create a simple plugin first. Luckily, it's really simple.

Before proceeding, we need to choose a name for our plugin. Thus, for my website, which runs Redmine too, I chose the name andriy_lesyuk. So, for this demo plugin I will choose just packtpub.

Name your customization plugin after your organization or site name. Use alphanumeric characters and dashes..

So now we will create a directory for our plugin in the plugins subdirectory of the Redmine root directory, which is /opt/redmine in my case. So the full path for the plugin will be /opt/redmine/plugins/packtpub.

After this, in the newly created directory, we will create the init.rb file (the entry point for the plugin) and put the following code in it:

require 'redmine' 'Starting Packt Publishing Plugin for Redmine'
Redmine::Plugin.register :packtpub do
name 'Packt Publishing customization'
author 'Andriy Lesyuk'
author_url ''
description 'The demo of the customization using the plugin.'
url ''
version '0.0.1'

In place of :packtpub write your plugin name (keep the colon at the beginning). What should be changed in the rest of the code, I believe, is quite clear.

When done, after restarting Redmine you should see your plugin in Administration | Plugins, as follows:

Of course, this plugin does nothing (besides putting itself into the plugin list), but that's all for now.

Customizing view files

Redmine is using the Model-View-Controller (MVC) architecture, where "view" files store the layout information. Most of the content of these files is just HTML code (the rest is eRuby, JavaScript, and so on). All views are located under the app/views path of Redmine. Any view can be overwritten just by copying the original view file into the appropriate path under the plugins app/views. So, let's now see how this works by reviewing one of the most common customization tasks, adding a logo to the layout

First we need to create a directory for images in our plugin. This must be the assets/images directory. After creating it put the logo image into this directory.

When done, create the app/views directory in the plugins root and copy the app/views/layouts/base.html.erb file there from Redmine preserving the directory structure (thus, the full target location in my case is plugins/packtpub/ app/views/layouts/base.html.erb).

Now open the base.html.erb file (the copy) and find the following line of code in there:

<h1><%= page_header_title %></h1>

This code renders the title of the page. Before this line, add the following line of code:

<%= image_tag('packtpub.png', :plugin => 'packtpub', :style => 'float:
left; padding-right: 1em;') %>

Here packtpub.png is the name of the image file and 'packtpub' is the name of the plugin.

Alternatively, the logo can be added using CSS (for example, by creating a custom theme). To do this you can specify the background image for #header. However, the #header area should not already have the background image, which can be set, for example, by theme. The advantage of this method is that the customization, most likely, won't need to be updated after upgrades.

After saving changes, restarting Redmine, and reloading any Redmine page you will get something like the following screenshot:

Track changes you make to copies of Redmine core files, as you may need to replicate them, if Redmine core files get modified with an upgrade.

The Plugin Views Revisions plugin of Vitaly Klimov allows you to bind the modified view file with certain Redmine version, thus, making it active only until an upgrade (this way preventing Redmine from crashes). More information can be found at plugins/redmine_plugin_views_revisions.

Using hooks

Redmine comes with "hooks" support. Hooks can be used to inject custom content into some pre-defined places in certain Redmine views. If possible, it is better to use hooks to add the content to the view instead of copying and modifying the view file, as for hooks you need to provide only the custom content and they are not affected by upgrades. Let's see how this works in another real-life example—let's add login instructions to the login page.

To be able to use hooks we need to add the hook listener to the plugin. To do this create the lib directory in the plugins root and place the packtpub_hook.rb file in it (you can use anything in place of packtpub in the filename). Now add the following code to the newly created file:

class PacktPubHook < Redmine::Hook::ViewListener
render_on :view_account_login_top, :partial => 'packtpub/login'

Here the name of the class, which is PacktPubHook, reflects the filename. :view_account_login_top is the hook, which gets called on the login form, and the :partial option contains the path to the custom content view file.

Now we need to create the file, which will contain the custom content. So first we will create the packtpub directory in app/views and then place the _login.html.erb file in it (note _ at the beginning of the filename—it is required). Now put your custom content, which can be just HTML, into the newly created file.

And finally we need to register our hook listener. To do this just add the following line of code to the init.rb file (under require 'redmine'):

require_dependency 'packtpub_hook'

Here packtpub_hook is the filename of the hook listener without extension.

Now when you restart Redmine and go to the login page, you should see something like the following screenshot:

The warning above the form is added using the hook.

The following table lists some other hooks, which can be interesting for you:




Bottom of the left column (the start page)


Bottom of the right column (the start page)


Below the form on the login page


Below the content on each page


Bottom of the left column (the project overview page)


Bottom of the right column (the project overview page)


Above the form on the new issue page

A full list of hooks can be found at


If the Redmine installation is not customized, it's a demo. Even Redmine.Org is customized (the ad on the sidebar, the plugins registry, and so on). All users prefer to customize the software they are using. Usually, Redmine users at least install some third-party plugins and a theme. But, in fact, all just mentioned can be described as installation and configuration. The real customization is what has been described in this article!

Some readers will, perhaps, never need what has been described here though (but, I believe the article was still interesting for them). But those who will, will be able to save time and money by doing the customization properly.

Resources for Article :

Further resources on this subject:

You've been reading an excerpt of:

Mastering Redmine

Explore Title