Redmine¶

Redmine is an Open Source, web-based project management and issue tracking service.

It is written using the Ruby on Rails framework and licensed under GNU General Public License v2

This guide explains how to install Redmine on Uberspace.

Note

For this guide you should be familiar with the basic concepts of

Prerequisites¶

Checkout which version of Ruby is supported by your desired version of Redmine. Redmine version 4 for example expects Ruby 2.2, 2.3, 2.4, 2.5 or 2.6.

Run uberspace tools version show ruby to show which Ruby version is currently active on your Uberspace and uberspace tools version list ruby to list all available ones.

To set Ruby version 2.5 you could run (but there is no need to do so if one of the above is already active):

[isabell@stardust ~]$ uberspace tools version use ruby 2.5
Selected Ruby version 2.5
[isabell@stardust ~]$

Ruby requires a database, so you should create an empty database now.

Note

Use the collation utf8mb4, otherwise Redmine will crash when users paste emojis in tickets.

[isabell@stardust ~] mysql -e "CREATE DATABASE ${USER}_redmine CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
[isabell@stardust ~]

Your domain needs to be setup:

[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
[isabell@stardust ~]$

You’ll need your MySQL credentials. Get them with my_print_defaults:

[isabell@stardust ~]$ my_print_defaults client
--default-character-set=utf8mb4
--user=isabell
--password=MySuperSecretPassword
[isabell@stardust ~]$

Installation¶

This instruction follows the official installation guide of Redmine for almost all steps, except for the step “Test the installation / Installing web server”.

Download and extract Redmine in the desired version. Ruby should not be stored into your DocumentRoot. Instead you may create a subfolder redmine in the Home Directory and place all files in there.

[isabell@stardust ~]$ wget https://redmine.org/releases/redmine-4.0.5.tar.gz
[isabell@stardust ~]$ tar xfv redmine-4.0.5.tar.gz
[isabell@stardust ~]$ mv redmine-4.0.5 redmine
[isabell@stardust ~]$ cd redmine
[isabell@stardust redmine]$

Copy the file config/database.yml.example to config/database.yml and edit the new file in order to configure your database settings for the “production” environment. You’ll find your mysql password using my_print_defauls client.

production:
  adapter: mysql2
  database: isabell_redmine
  host: localhost
  username: isabell
  password: "my_secure_mysql_password"

Redmine uses Bundler to manage dependencies. Install Bundler running gem install bundler.

Install all dependencies running bundle install --without development test rmagick --path vendor/bundle:

[isabell@stardust redmine]$ bundle install --without development test rmagick --path vendor/bundle
Bundle complete!
Gems in the groups development, test and rmagick were not installed.
Bundled gems are installed into `./vendor/bundle`
[isabell@stardust redmine]$

Create a secret token running bundle exec rake generate_secret_token.

Create the database structure with the command RAILS_ENV=production bundle exec rake db:migrate.

Redmine provides a set of default configuration data like a first admin user, some access groups, default project settings etc. which may be added running RAILS_ENV=production bundle exec rake redmine:load_default_data.

All file permission should be fine automatically on Uberspace.

The installation is now done, what’s missing is the connection to the webserver.

Connecting the webserver¶

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 request for the Ruby app along to the appserver. The appserver will then actually run your Rails app.

Ruby offers many appservers. You may use Puma, which is documented extensively in the UberLab as well.

[isabell@stardust redmine]$ gem install puma
Building native extensions. This could take a while...
Successfully installed puma
1 gem installed
[isabell@stardust redmine]$

Tip

Use the installation with the gem command above and not with bundler, as suggested in the Redmine installation guide, since this may trigger a bug.

Create a configuration file for Puma called config.rb and add the following structure. Adapt the highlighted lines to your setup.

#!/usr/bin/env puma

# The directory of your Ruby app
directory '/home/isabell/redmine'

# The path to the Redmine rackup file
rackup '/home/isabell/redmine/config.ru'

Note

puma is running on port 9292.

To make the application accessible from the outside, configure a web backend:

[isabell@stardust ~]$ uberspace web backend set / --http --port <port>
Set backend for / to port <port>; please make sure something is listening!
You can always check the status of your backend using "uberspace web backend list".
[isabell@stardust ~]$

You could now start Puma manually and everything would work. But to start it automatically Uberspace offers the service supervisord.

Create and edit the file ~/etc/services.d/redmine-daemon.ini and add the following content to it.

[program:redmine-daemon]
command=/opt/uberspace/etc/%(ENV_USER)s/binpaths/ruby/puma --config %(ENV_HOME)s/redmine/config.rb --environment production
autostart=yes
autorestart=yes

The --config parameter provides the path to the Puma configuration file. Be aware that the %(ENV_X)s is a Python syntax, which will expand to /home/isabell (so the »s« is part of the syntax, not of your path).

Lastly, tell supervisord to refresh its configuration and start new services by running supervisorctl update.

Redmine should now be available on your configured domain.

Configuration¶

If you’ve added the default configuration for Redmine, then you will have a default profile with the following credentials.

Name: admin
Password: admin

Redmine will ask you to change the password right after you login for the first time.

Create some users first. The create some projects. Add members to your projects.

Best practices¶

Rename the admin user to any other username
Set up groups for teams, and assign new tickets to teams instead of individuals so everybody can see them

Updates¶

Check for new download versions regularly and follow the Security Advisories to stay informed about important updates.

Follow the Redmine Upgrade Guide to update the application, which consists of the same steps as the installation guide above, plus backup and restore of existing data.

Tested with Redmine 4.0.5, Ruby 2.6, Uberspace 7.3.9.2

Written by: Dan Untenzu <mail@pixelbrackets.de>