Install Redmine as Issue Tracking Service

tl;dr ITS tools help a lot to collect and organize tasks - I share a shortlist of self-hosted solutions and what to consider when installing Redmine

To organize tasks and collect descriptions of errors and improvement requests the implementation of an Issue-Tracking-System (ITS) is a suitable option. ITS Software helps to

  • digitalize this information (no todo lists or sketch notes burried somewhere)
  • provide templates to write a formal description
  • categorize and create relations
  • assign tasks to people or departments and keep track of workflows
  • prioritize
  • discuss and document steps to resolve an issue (fails also, a search for those tickets might save a lot of time later)
  • monitor and evaluate the performance of a task
  • connect with APIs and automatically collect tickets (e.g. catch exceptions and create issues for them)
  • have a single point of truth

For the development of Open Source software and my personal side projects I like to use the issue tracker included in GitLab. Register as user, create a public or private project and start writing issues. No need to install anything, the tool is advanced and has a very nice interface.

GitLab Screenshot

In need for self-hosted software I evaluated several existing solutions.

  • Phabrikator (PHP)
    • ➕ Large featureset
    • ➖ Very technical GUI
  • Flyspray (PHP)
    • ➕ “Do One Thing and Do It Well“, reduced GUI, good milestone management
    • ➖ Small fonts and icons, no API
  • The Bug Genie (PHP)
    • ➕ Well organized issue tracker, with boards, detailed API
    • ➖ Technical GUI, too much options & views (reminds me of older TYPO3 versions, when editors were able to do the same using five different ways), no unique issue numbers
  • GitLab (Ruby)
    • ➕ Nice GUI, steady development
    • ➖ Good in conjunction with GitLab, not so handy as standalone system
  • OpenProject (Ruby, Redmine Fork)
    • ➕ Extensive, with Wikis etc, very modern GUI
    • ➖ More a project manager than an issue tracker, too much PM views activated by default
  • Redmine (Ruby)
    • ➕ Clear GUI, understandable configuration, easy to split into subprojects, lots of high-quality plugins available
    • ➖ Unclear documentation, unsteady development

»The Bug Genie« seems to be the best option in PHP. Not having a unique issue number is a no go flag however. Redmine is a popular, time-proven software and good to use & manage.

Uberspace provides a tutorial for older Redmine versions. So here are some things to consider for Redmine 4.

To install Redmine you may stick to the official installation guide. From personal experience I recommend to use utf8mb4 as database collation. Otherwise Redmine may crash if users paste emoji into ticket descriptions.

The second last step of the official guide just says, that the given description is not suitable for production. Some other guides for »Passenger«, »Unicorn«, »Thin«, »Puma«, or »hellip« should be used instead to serve the app. Well. Okay.

A Ruby speciality is that it requires a so called »appserver« as connector between your application and the webserver. The webserver, like Nginx or Apache, will handle all incoming web request and pass only requests for the Ruby app along to the appserver. The appserver will then actually run your Rails app. There are other ways as well, but this is the usual.

Ruby offers many appservers, also written in Ruby. These are named »Unicorn«, »Puma« and so on. Ah, that clicks.

To install Puma run gem install puma, find a free port, and add a Puma configuration file config.rb into the Redmine folder with the following content (change the port and paths as needed):

#!/usr/bin/env puma

# The directory of your Ruby app
directory '/home/my-username/redmine'

# The path to the Redmine rackup file
rackup '/home/my-username/redmine/config.ru'

# Bind Puma to a port
bind 'tcp://0.0.0.0:9000'

To connect the appserver with the Apache webserver create the file public/.htaccess, and add this downscaled content:

DirectoryIndex disabled
RewriteEngine On
RewriteRule ^(.*) http://localhost:9000/$1 [P]

Last but not least configure a deamon to start Puma and Redmine automatically. Follow the supervisord guide. These lines are sufficient for the ini file:

[program:redmine-daemon]
command=/opt/uberspace/etc/my-username/binpaths/ruby/puma --config /home/my-username/redmine/config.rb --environment production
autostart=yes
autorestart=yes

The installation is done now. If you've added the data preset for Redmine, then you will have a default administrator profile available. You should login in immediately and change the default password as well as the username (never use »admin« as username).

Redmine Screenshot

Now create some users first. Then create some projects. Add members to your projects. A best practice is to set up groups for teams and assign new tickets to teams instead of individuals, so everybody can see them.

Good to know: The update guide basically consists of the same steps as the installation guide above, with just some addional steps for backup and restoring of existing data.

No comments on this notepad. If you would like to add something, then dont hesitate to contact me via E-Mail or Twitter.