About Redmine

Today there are a lot of choices between project management tools for development. I have tried JIRA, Asana, ClickUp and a few others. Somehow I always return to the essence of where it all started for me years ago: Redmine.

Redmine is a web-based project management tool with a long history, stability and still a rock-solid choice and has endless extending possibilities. (in fact: it's forked and used as a base for many other project management tools).

I host a virtual server that runs openSUSE Leap 15.3. Despite counting thousands of packages in their repositories: Redmine is not included, but fortunately, all the requirements for Redmine are present.

This guide will focus on recent versions of openSUSE. In case you run a Debian-based distribution (ex. Ubuntu Linux): there is a comprehensive installation guide for Redmine on their official website.

Installation on openSUSE Leap 15.3

Setup layout

This is what we will setup (in a nutshell):

• We install a **clean version **of Redmine from GitHub

• We hook it up to a MySQL-based database server (MariaDB is a splendid choice)

• We use Passenger as an app server (since Redmine is an application, not a website so it can not directly communicate with Apache)

• We use Apache2 as a web server and Acme.sh to get SSL certificates and enforce a solid https connection.

Get the system dependencies

Apache and MariaDB

Apache and MariaDB are easily installable through the original repositories. You can follow the well-explained steps in the original installation guide to install:

• Apache

• MariaDB

Ruby libraries and Passenger

Redmine is written in Ruby so we need to install all the necessary stuff to get a Ruby application and app server working in openSUSE:

sudo zypper in ruby2.5 ruby2.5-devel ruby2.5-rubygem-bundler rubygem-passenger rubygem-passenger-apache2 yast2-ruby-bindings

Install the latest version of Redmine

Redmine maintains an official mirror of its repository on GitHub. To get the latest version, you can do a git clone in a directory where you would like to host the application like this (replace /srv/www/vhosts if you like to keep your sites in a different location):

mkdir /srv/www/vhosts
cd /srv/www/vhosts
git clone https://github.com/redmine/redmine.git

Once git has finished cloning the repository, enter the newly created redmine directory and check out the latest stable version.

At the time of writing this article, the most stable version was 4.2.3. Verify if a more recent version is available on the Redmine GitHub page.

cd redmine/
git checkout 4.2.3

You should now get confirmation that git HEAD is at the desired version:

HEAD is now at 9f7103277 tagged version 4.2.3

Prepare the database

Assuming you have set up MariaDB correctly (if not, go back 2 chapters ⤴️!), add a new user and database for redmine and grant permissions.

Login as root user (or a different user with 'grant' permissions)

sudo mysql -u root

Once you are at the MySQL command line interface (CLI), create a new database for your Redmine instance.

CREATE DATABASE redmine;

Next, create a user, obviously, replace replace_with_secure_password with a... secure password of your choice 👌!

CREATE USER 'redmine'@'localhost' IDENTIFIED BY 'replace_with_secure_password';

Add permissions for the new redmine user to manage the redmine database:

GRANT ALL PRIVILEGES ON redmine.* TO 'redmine'@'localhost';

Finally, flush the privileges so we can start using the new redmine user and exit the CLI.

FLUSH PRIVILEGES;
EXIT;

Prepare the Redmine application

Create the configuration file

Now it's time to tell Redmine where it can find the right database and connect to it. In the config folder are some useful example files. We'll follow the official installation guidelines and copy the example file as a starting point.

cp config/database.yml.example config/database.yml

Open the file with your text editor (vim for experts, nano for starters!) and change the production settings to your database values:

production:
  adapter: mysql2
  database: redmine
  host: localhost
  username: redmine
  password: "the_secure_password_you_chose"

Note that I am assuming you've stuck to a MariaDB database as described above. mysql2 is the driver Redmine will be using to connect. If you used a different database setup, be sure to check the Redmine documentation for other options.

Install the Redmine dependencies

Since Redmine is written in Ruby, it uses some specific dependencies: we will use 'bundler' to install these in 1 line. Note that we have installed 'bundler' during the preparation of openSUSE above.

We exclude all development and test files since we won't be using them.

bundle install --without development test

I hope you succeeded! Now run the following script, it will generate a token that will be used for cookie storage.

bundle exec rake generate_secret_token

Fill the database with the initial structure

Redmine will need an initial setup of database tables to function correctly. Run these 2 scripts to build the tables. (it will also verify that you have done the Redmine configuration correctly!)

RAILS_ENV=production bundle exec rake db:migrate
RAILS_ENV=production bundle exec rake redmine:load_default_data

With the second command (load_default_data), the script will ask for a default language. Make your choice with the given options. If you want English, you can skip this question by just hitting enter. Once finished you should get the notification that the data was successfully loaded:

====================================
Default configuration data loaded.

Set the permissions for the file system

Redmine needs a storage location for file and cache storage, create these folders and set the permissions accordingly so that our Passenger server can access them later on.

Note that I am assuming that you want to run the application as the default 'http' user in openSUSE, which is wwwrun. Change to your wishes if you have or want a different configuration.

mkdir -p tmp tmp/pdf public/plugin_assets
sudo chown -R wwwrun:www files log tmp public/plugin_assets
sudo chmod -R 755 files log tmp public/plugin_assets

Setup apache with passenger

Passenger is an application server that will 'steer' Redmine to the web browser in a safe and efficient way. We will not use Passenger directly as an HTTP endpoint. We will use Apache for this.

The main reason I prefer this type of configuration is port management: If you already have a different website running (or applications like phpMyAdmin for example), you are probably already using ports 80 and 443!

Activate Passenger as a module in Apache

We already installed Passenger and the module for Apache during the openSUSE setup. So you can simply enable the module:

sudo a2enmod passenger

This will allow Apache to interpret the Passenger terms inside an Apache configuration file and execute the correct application when the user requests the website (or better: 'application')

Add a virtual host file

I hope you have thought of a (sub)domain by now where you would like to host your Redmine installation. To keep the 'vhost.d' folder clean, I like to rename each virtual host file to the domain of the site itself. **It doesn't matter how you call the file, just don't forget the .conf extension.

touch /etc/apache2/vhosts.d/redmine.domain.conf

Now edit the file (with your favorite text editor! 📄) and add the following configuration. Be sure to replace the domain name and email!

<VirtualHost *:443>
        ServerName redmine.domain_name.com
        ServerAdmin your@email.com
        DocumentRoot /srv/www/vhosts/redmine/public
        PassengerAppRoot /srv/www/vhosts/redmine
        PassengerDebugLogFile /srv/www/vhosts/redmine/error.log
        <Directory /srv/www/vhosts/redmine>
          AllowOverride All
          Require all granted
        </Directory>
</VirtualHost>

<VirtualHost *:80>
        ServerName redmine.domain_name.com
        RedirectMatch permanent ^/(.*) https://redmine.domain_name.com/$1
</VirtualHost>

Notice the bottom configuration<VirtualHost *:80>, we will forward all unsafe requests on http (port 80) automatically to https (port 443) for safety reasons.

You could theoretically test your installation by now if you reload your Apache webserver but we have not yet configured an SSL certificate for https connections.

Before proceeding to the next step: make sure the DNS settings of your domain name (the one you defined in the virtual host config above) are configured to point to the IP address of your openSUSE installation.

Get a https certificate with acme.sh

Unless you are running your Redmine installation on a local intranet or don't care about an SSL connection to your site (you should!) you can configure your certificate by now.

If you don't have strategy or setup for this: I recommend reading my 5-minute guide on how to set up SSL certificates on Apache2 with acme.sh.

Verify the installation

I hope you have made it this far! If you followed all the steps correctly and visit the domain that you pointed to for your Redmine installation, you should see the following screen:

Login to Redmine

Change the admin user

Very important: By default, the admin is activated with the password 'admin'. Change this password immediately after your installation is up and running.

Click 'Sign in' in the header (top right corner) and log in with the following credentials:

• Login: admin

• Password: admin

Now change the admin password to something more secure (Redmine requires minimum of 8 characters).

After you've done this, you're good to go! In case you come across errors at this point, be sure to check the permissions of the redmine folder so that Apache can access them.

Where to go from here?

Congratulations 🎉! you have Redmine stable and running. I suggest you explore the features of your brand-new installation (with the aid of the Redmine documentation)

Once you master the basics: learn how to unleash the full power and extend/customize Redmine to your needs.

Have fun!