It's always better to meet rather than just hear about. I cannot imagine a person who is familiar with Redmine but who has never seen it. So, let's start by checking out the Redmine interface.

As mentioned earlier, Redmine has an easy-to-use and simple user interface. The following screenshot shows its Home page:

In the top-left corner of the page, we have the global menu (Home, My page, and so on). To the right-hand side of the global menu, we have the account menu (Logged in as). These menus are repeated on every page of Redmine. The blue area below these menus contains the site title. The content area contains the site introduction and recent news for all projects.

Generally, a page in Redmine can be either a global one (the previous screenshot) or a project one:

This is the start page of the project, which is also referenced as the project home page. Most of the time, when working with Redmine, you will be interacting with project pages. The blue top area on a project page contains the project title. The project menu is displayed in this area below the title. The project home page contains the description of the project, issues summary, members summary, and latest news of the project. Most project pages also include the sidebar with some contextual information, such as links, and sometimes forms.

As one of the primary features of Redmine is issue tracking, let's check out the issue list:

As you can see, the layout is quite simple and friendly. Collapsible boxes such as Filters and Options are used all over Redmine to hide rarely used elements. If table headers contain links, as in this case, they can be used to change the order of rows. Below the issue listing, you can see export links (near Also available in:). Such links are usually provided if the content can be exported to other formats.

The following screenshot illustrates the issue page:

In the top-right corner of the content area of this page, you can see the contextual menu, which is also duplicated at the bottom of the page. Similar contextual menus are also used for many other Redmine objects such as projects, Wiki pages, and so on.

The issue page is an example of a Redmine page that contains multiple hidden forms. Thus, such a form can be activated if you click on the Edit, Quote, and Add links (all three links open the same form). Trash icons near Watchers are another common Redmine interface element that can be used to delete an object.

By the way, some hidden forms, such as the one that can be activated by clicking on the Add link to the right of the Watchers heading on the sidebar, are shown in a light box:

Another interface element that is used extensively in Redmine is the tabular menu. Such a menu can be found on, for example, the project's Settings page:

Here, you can see another interface element that is widely used in Redmine—the text area, which supports Wiki syntax. Such a text area usually comes with the text formatting toolbar.

The following screenshot illustrates the administration settings:

Links to administration pages are located on the sidebar. The current page, which is Settings, uses the tabular menu that we saw in the project settings. On the General tab of this menu, you can see the Wiki-enabled Welcome text field.

This was a short walkthrough of the Redmine interface to let you get used to it and understand its basic concepts. I hope you see that it is easy to use. We will review the interface in detail in subsequent chapters.

Redmine can be used with MySQL, PostgreSQL, SQLite or Microsoft SQL Server database backends (the first three ones are actually natively supported by Ruby on Rails). But which one should you select for your Redmine installation? It's perhaps too important a question to be ignored in this book. No, I'm not going to praise some databases or criticize others—that's out of scope here. Instead, I'll cover things that you should consider when choosing a database backend.

Having worked with Redmine for quite a long time, I have noticed that most users use it with MySQL. Despite their reasons for choosing it, this means that Redmine has been better tested with this database backend. This argument becomes even more important if we consider that some plugins use SQL directly (that is, without the Rails SQL query builder).

But if you are seeking a reliable source on which database is faster with Redmine, you can check out the Redmine build logs at http://www.redmine.org/builds/index.html. These logs contain results of tests for different versions of Ruby and different database backends. Thus, at the time of writing this section, tests of the latest revisions, r14600, r14597, and r14596, in the latest stable branch 3.1-stable were running for the following time periods (only for ruby-1.9.3-p194):

In the previous table, I used the data from the aforementioned logs. Certainly, by the time you read this section, there will be new data, but as practice shows, the results will most likely be the same. Anyway, you can check out new data or take more revisions into account to recheck the results.

So, according to this data, SQLite is the fastest, SQL Server is the slowest, and PostgreSQL is a little slower than MySQL.

But don't hurry to make a decision in favor of the fastest backend. Unfortunately, SQLite has scalability issues (you can't put it on a separate server) and will behave incorrectly in a multiuser environment. And I'm quite sure that you'll want to serve many users at a time.

You should also note that in addition to the comparative slowness, Microsoft SQL Server runs only on Windows, its full edition is not free, and the free one (Express) is limited. Also, support for this database backend was added especially to Redmine and is not native to Rails. This means that it was not tested as well as other alternatives. Anyway, if you already have SQL Server running in your corporate network, it can be a good idea to use it for Redmine.

Good readability helps improve perception. Rich formatting is very important for issue tracking software as it allows us to highlight more important things, in this way drawing special attention to them. In Redmine, rich formatting can be achieved using a lightweight markup language—Textile or Markdown—and is supported almost in every text area. Both of these markup languages use plain-text formatting syntax.

Textile has been used by Redmine as the default and the only available formatter for many years. It is greatly supported and perfectly tested. Any experienced Redmine user is familiar with Textile and many Redmine plugins extend its syntax. Particularly for these reasons, the majority of Redmine installations, including the official website Redmine.org, use this formatter. So, most Redmine users definitely use Textile.

However, I did not see Textile being used by any other application except Redmine. On the contrary, Markdown seems to have become the de facto standard for rich formatting that is based on plain text. Thus, it is used by GitHub (in fact, it was GitHub that made it so popular) and Stack Overflow. It can be said that most developers who use a markup language use Markdown.

This means that for a fresh installation, if your target audience have not gotten used to Textile yet, you should probably select Markdown. Also, currently Redmine does not come with any converter from Textile to Markdown and I'm not sure whether it ever will (as it's complicated). So, if you choose Textile for your fresh installation, you will probably be tied to it forever. On the other hand, 3.1 is actually the first Redmine version for which the Markdown formatter is not considered to be experimental any more (it was added in 2.5). This means that this formatter has just entered the intensive testing phase (you can still help with this though). Another possible reason for keeping Textile as your formatter is that many existing Redmine users, if any of them are going to use your installation, will probably expect Textile to be used. So, generally you are better off asking your users.

But let's not be too verbose and compare the basic rules of these formatters:

Still, which one is more powerful? Markdown is known to be more feature rich in general as, for example, it supports some HTML tags. However, its Redmine implementation is limited. Thus, no HTML tags are actually supported under Redmine. This can nonetheless change in the future, of course. On the contrary, the long usage history of Textile by Redmine has made it more powerful at the moment. See also Chapter 6, Text Formatting.

Source Control Management (SCM) is better known as revision control management. Redmine currently supports the following revision control systems: Subversion (SVN), Git, Mercurial, Bazaar, Darcs, and CVS.

As it has been mentioned, Redmine can use SCMs not just as source code readers. It can also associate a revision with issues (and have revisions listed on issue pages). It can close an issue automatically and/or change its done ratio when an appropriate commit is made to the repository. It allows us to use the Wiki syntax in commit messages. It also allows us to refer to a revision, a commit, or a file from any Wiki-syntax-powered content, which can be a Wiki page, an issue description, a project description, a forum message, and so on. But all this makes Redmine an (advanced) source code browser, not an SCM manager (which can be done with plugins though). Then why is choosing the right SCM so important?

Most likely, you will want a deeper integration between Redmine and SCMs as soon as you know the options. Thus, it can be said that Redmine supports three levels of integration:

The basic code browser level requires corresponding SCM clients to be installed on the same server on which Redmine is running, so you may want to use only some of the supported SCMs. Also, the basic support is not equivalent for all SCMs. Thus, the revision graph (similar to the one on GitHub; see the following screenshot) is supported only for Git and Mercurial. Also, these two SCMs can be only local (repositories should be on the same server where Redmine is).

Also, Redmine comes with Redmine.pm—a Perl module for the Apache web server that can be used to authenticate Subversion, Git, and Mercurial users against Redmine. If the Redmine.pm tool has been integrated, you can control who has access to the project's repository and what kind of access (read or write) they can have by simply managing project members (and roles). Something similar (with additional changes made to Redmine and/or the system) can also be achieved for Bazaar. However, Subversion and Git SCMs are best supported by the Redmine.pm tool and their support works out of the box. At the same time, you will most likely have problems configuring other SCMs to authenticate against Redmine.

The only missing functionality for Redmine to become a full-featured SCM manager is the ability to create repositories. But such functionality also comes with Redmine and is provided by the reposman.rb command-line tool. This tool supports Subversion, Darcs, Mercurial, Bazaar, and Git (that is, all except CVS). However, the problem with it is that to make it work, you need to create a cron job that will execute this tool periodically. Luckily, alternative solutions that do not have such problems are provided by third-party plugins such as SCM Creator and Redmine Git Hosting (see also Chapter 10, Plugins and Themes).

When choosing SCM, you should also consider your requirements, your experience, the preferences of your team or audience, ease of use, and so on. However, the best integrable SCMs seem to be Subversion and Git.

Redmine as a Ruby on Rails web application should be run under a web server. This can be an independent web server (such as Apache, Nginx, or Lighttpd) that runs Ruby on Rails using either Passenger or FastCGI, or a dedicated Ruby web server such as Puma, Unicorn, Rainbows!, or Thin.

A big option list, isn't it? And these are not even all the possible options. Redmine can also be used with JRuby under a Java virtual machine. It can be run under standalone Passenger, under Mongrel, WEBrick, and more. But the previously mentioned options were chosen by practical use, and therefore they are the most common. That's why we are reviewing only those options here.

These options can be divided into three categories:

Ruby is often compared to PHP, but actually these technologies are very different. For PHP guys, which include me as well, the use of a web server written in Ruby to run a Ruby application sounds weird. But in fact, a Ruby application, like a Java one, runs under a virtual machine. Therefore, Apache, for example, needs to run a Ruby virtual machine in order to run a Ruby application. This way, eventually we get at least three processes: a web server, an application server, and the application itself. So, running a Ruby application under a Ruby server seems to be reasonable, because in this case, we get only two processes: an application server which serves as a web server as well and the application.

The lack of good multithreading support is a known problem of Ruby virtual machines, and this is the main reason people use a Ruby application server in conjunction with a web server to run Ruby applications in production. Thus, they launch many instances of a Ruby server and use some web servers as a load balancer to forward requests to these instances and as a web server to dispatch the static content (images, CSS files, and so on). The best combination for this category, according to many benchmark results, is Nginx plus Puma or Unicorn.

But in practice, for this configuration, people also often use a dedicated load balancer in addition to the web server. This can be either a special application, such as HAProxy, or a web server with support for reverse proxy mode. For Apache, such a mode is provided by the mod_proxy module. Nginx and Lighttpd have built-in proxies. In addition, some people use special software for monitoring of Puma/Unicorn instances, for example, Monit.

Certainly, the category just discussed is for advanced use and high-loaded services. The most commonly used, easiest to install, and best documented is the third category: a web server running a Ruby application using the Passenger module (also known as mod_rails) or the FastCGI module. The Passenger module is, in fact, another Ruby application server. It differs from Puma/Unicorn in that it runs as a module of a web server and not as a standalone application server (while the latter is possible). Unfortunately, the Passenger module has some limitations. It does not work under Windows and is not available for Lighttpd. For Lighttpd to run Ruby applications, people have to use FastCGI. Here, FastCGI is the name of the protocol that is used by web servers to communicate with Ruby virtual machines. Modules of the same name that implement this protocol exist for Lighttpd, Apache, and Nginx.

Generally, Passenger is more popular than FastCGI. Thus, it is used by the BitNami Redmine stack and TurnKey Redmine appliances (systems for easy Redmine deployment). It is suitable not only for small-sized and middle-sized websites, but also works great for high-loaded ones. Therefore, guys from the Ruby on Rails framework recommend using Passenger in favor of other options (check out http://rubyonrails.org/deploy).

When run under a web server, Passenger creates at least two processes: itself and an application instance. This can become a problem if it is used on a cheap OpenVZ-powered VPS hosting, where the amount of memory that is used by an application is very critical. This is where FastCGI helps. When run using FastCGI, Redmine occupies at least one process (an application instance).

If you still don't feel sure about which option to choose, let's summarize:

While choosing, you should also consider your other requirements and services you plan to run on the same server. For example, you will definitely need Apache if you plan to use Redmine.pm for authentication of Subversion/Git users against Redmine, as it's an Apache module.

At the time of writing these words, on the official Redmine website, you could find four different stable versions for download. They are a new release of 3.2, maintenance releases for 3.1 and 3.0, and another maintenance release for 2.6. This indicates that the installation of an application does not always mean the use of the most recent version.

But let's try to find out why the Redmine guys decided to release four versions of the application. Version 3.x uses Rails 4 and version 2.x uses Rails 3. For Ruby applications, a migration between major Rails versions, such as from 3 to 4, is a very serious step that often requires many changes to be made to the environment, custom tools, and so on. Major Rails versions are usually not compatible, so it's normal to give people some additional time for the migration. That's why we have 2.6 on the list. However, the Redmine developers also decided to give additional time for migration from Redmine 3.0 and 3.1 to 3.2. There were actually no special reasons for this, I believe.

By the way, the same that applies to Rails applies to Redmine. Major Redmine versions, such as, 1.x, 2.x, and 3.x, are known to be generally incompatible. That is, plugins must usually be modified a lot to work under the next major version. Therefore, their support for the new major version often comes with a big delay. On the contrary, minor versions, such as 3.0 and 3.1, are usually quite compatible, so plugins may run under the next minor version without any changes. And finally, tiny Redmine versions, such as 3.1.0 and 3.1.1, usually deliver fixes, which do not affect the working of plugins.

In most cases, people use the most recent version of an application, which is 3.2.x for Redmine at the moment. However, some Linux distributions or appliances may come with older versions. So should you stick to the distributed version or should you install the very recent one? Note that in the case of using distributions and appliances, switching to the most recent version usually involves performing manual migration and further manual maintenance. So, to be sure about what to choose, you should at least know what the difference between the versions in question is.

Therefore, let's shortly review the current stable versions of Redmine (the ones that are available at the time of writing this section):

Basically, due to the migration to Rails 4—and, therefore, huge changes in API at the time of writing this book—not all Redmine plugins had been ported to Redmine 3.x.x yet. You should consider this while choosing the version for your installation if you use or plan to use any plugins.

In 2011, one of the most active Redmine developers, Eric Davis, with a group of other contributors from a company named Finnlabs, forked Redmine into ChiliProject. Unfortunately, this project was recently discontinued.

However, while working on ChiliProject, Finnlabs decided to make a custom version of this application. Eventually, having understood that ChiliProject was not good enough for them, they made their fork public and named it OpenProject. Right now, this fork is actively developed and already has quite a large community. Finnlabs also changed the style of the project—they made it more commercially oriented and created the OpenProject Foundation, which is funding it. These changes had a positive effect on the fork, which now looks quite cool and promising. However, it's obvious that the project is too young to replace Redmine. Also, it has not proven its durability yet (ChiliProject looked promising too).

The goal of this chapter was to familiarize you with Redmine and get you ready to dig deeper into this amazing web application. Therefore, we not only reviewed the advantages and the interface of Redmine, but also checked its installation components. We even discussed forks of Redmine, as I believe it's good to know about them if you are going to become a member of the Redmine community.

I have tried to share as much knowledge about the installation components of Redmine as possible so that you can understand them better, learn what options you have, and be able to choose the right one. Still, remember that usually the best option is the one that is used by most users. So, if you choose an uncommon option, you should be sure about your reasons for doing so.

The knowledge that you have gained by reading this chapter should come in handy in the next one, as you will need to decide which components to use for installation.