It’s good to be back. For a start, I thought that I would write an update to some of my previous posts, starting with the installation of Redmine.

We will be installing the latest version of Redmine (version 4.2.1) at the time of writing on Ubuntu Server 20.04, with Apache 2 and Phusion Passenger as the web server and application server respectively, and MariaDB (version 10.6) as the relational database.

We will install the above components step by step, then do a final integration at the end.

Background

With the emergence of cloud computing, there has been a rise of several software project management solutions that are available to assist developers manage and keep track of their code changes. Many are offered as SaaS solutions such as Github, Gitlab, Bitbucket, Azure Devops and AWS CodeDeploy (just to name a few).

Even with all the above SaaS offerings, for individuals or companies that need a higher degree of control of their applications, or due to regulatory reasons need to have their servers operated in house, Redmine is still a good solution for managing code changes and hosting repositories. It has a minimalist interface, therefore easy enough for a typical software engineer to understand, and also quite customizable due to its open source nature.

For more details on the features of Redmine, check out the Redmine site here.

Step 1: Install Redmine pre-requisites

NB: Unless specified, run all the following commands on the bash prompt of your VPS/Dedicated Server.

(Optional) Update your Geographic Area

Redmine will use the local timezone as defined in your geographic area) and set the timezone on your server:

sudo dpkg-reconfigure tzdata

Substitute the values in square brackets with your own respective values:

Geographic Area: [Your Geographic Area e.g. Africa]

Time zone: [Your City e.g. Nairobi]

Install and Configure MariaDB

First off, we shall start by installing MariaDB server. There are a few ways we can do this, but in order to install the latest version (10.6) at the time of writing, we will have to add an external repository that is managed by the MariaDB team.

Add the MariaDB GPG Signing keys

sudo apt-key adv --fetch-keys 'https://mariadb.org/mariadb_release_signing_key.asc'

Add the Ubuntu repository for MariaDB 10.6

sudo add-apt-repository "deb [arch=amd64,arm64,ppc64el] https://mariadb.mirror.liquidtelecom.com/repo/10.6/ubuntu $(lsb_release -cs) main"

Update the local repo cache

sudo apt update

Install MariaDB 10.6

sudo apt install -y mariadb-server

Secure MariaDB

It is strongly recommended securing MariaDB (or any other relational DBMS) post install, as the default settings have plenty of security holes. Conveniently, MariaDB comes with a custom command for enhancing its security which is as follows:

sudo mysql_secure_installation

Then answer the prompts as follows:

Enter current password for root (enter for none): (Press enter here so as to enter a strong password in the next prompt)

Switch to unix_socket authentication [Y/n] y

Change the root password? [Y/n] y (You will be prompted to enter and confirm your new MariaDB password. Remember to enter a strong password here)

Remove anonymous users? [Y/n] y

Disallow root login remotely? [Y/n] y

Remove test database and access to it? [Y/n] y

Reload privilege tables now? [Y/n] y

If all goes well you should see the following printed to your console:

Cleaning up...

All done!  If you've completed all of the above steps, your MariaDB
installation should now be secure.

Thanks for using MariaDB!

Install Ruby, Apache and Phusion Passenger

Apache is arguably the world’s most popular web server. It is also quite commonly used to serve Redmine installations. Since Redmine is built in Ruby on Rails, we will also have to have ruby installed on the server. We will use the version provided by Brightbox, as I have found they have upto date ruby versions, plus they are more convenient to install. We will have to install at least ruby version 2.7.2, which is the minimum version required for Redmine 4.2.

Phusion Passenger is an application server built primarily to serve ruby on rails applications, and comes with runtimes that support both Apache and Nginx. In our case, we will be installing the runtime for Apache2. I have adapted these commmands from the Phusion Passenger docs available here.

Additional packages we will have to install include:

  • imagemagick - required for the correct display of gantt charts in redmine

  • libmysqlclient-dev - required for the compilation of the mysql2 ruby gem that redmine uses

  • build-essential - required for the compilation and building of some ruby gems used by redmine e.g racc, nokogiri, nio4r, websocket-driver 0.7.5. Bundler builds then installs them using native extensions, and displays a message such as the following:

Fetching websocket-driver 0.7.5
Installing websocket-driver 0.7.5 with native extensions

Add the Ruby Brightbox PPA

sudo add-apt-repository ppa:brightbox/ruby-ng

Add the Passenger GPG keys and repository

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 561F9B9CAC40B2F7

sudo sh -c "echo deb https://oss-binaries.phusionpassenger.com/apt/passenger $(lsb_release -cs) main > /etc/apt/sources.list.d/passenger.list" 

Fetch the latest changes from the online repository

sudo apt-get update

Install apache, ruby, passenger and additional packages

sudo apt-get install -y ruby2.7 ruby2.7-dev ruby-switch libapache2-mod-passenger apache2 libmysqlclient-dev build-essential

This will take some time depending on the speed of your internet connection.

Validate the Ruby Version Installed

ruby --version

You should see printed to the console:

ruby 2.7.2p137 (2020-10-01 revision 5445e04352) [x86_64-linux-gnu]

Enable the passenger apache module

sudo a2enmod passenger

You should see printed to the console:

Module passenger already enabled

Validate the passenger installation

sudo /usr/bin/passenger-config validate-install

You should see the following printed to the console. When asked to choose what to validate, select Passenger itself.

What would you like to validate?
Use <space> to select.
If the menu doesn't display correctly, press '!'

 ‣ ⬢  Passenger itself
   ⬡  Apache

-------------------------------------------------------------------------

 * Checking whether this Passenger install is in PATH... ✓
 * Checking whether there are no other Passenger installations... ✓

Everything looks good. :-)

Validate the installation of apache

apachectl -v

You should see:

Server version: Apache/2.4.41 (Ubuntu)
Server built:   2021-10-14T16:24:43

Step 2: Create the MariaDB Redmine user

Login to the MariaDB console:

mysql -u root -p

You will then be prompted to enter the root password which you created earlier. On a successful login you should see printed to the console the following:

Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 31
Server version: 10.6.4-MariaDB-1:10.6.4+maria~focal mariadb.org binary distribution

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]> 

Once logged in, run the following SQL commands on the MariaDB console:

NB: Modify the values in square brackets with your preferred values. Please keep track of them as they will be essential later on in the installation process.

MariaDB [(none)]> create database redmine_production;
MariaDB [(none)]> create user 'redmine_user'@'localhost' identified by 'your_redmine_password';
MariaDB [(none)]> grant all privileges on redmine_production.* to 'redmine_user'@'localhost' identified by 'your_redmine_password';

Quit the MariaDB console:

MariaDB [(none)]> \q

Step 4: Install Redmine

First, we will download the Redmine source code to the /tmp directory, then install it in the /usr/share/redmine directory. I will install Redmine version 4.2.3, the latest at the time of writing.

Go to the /tmp directory

cd /tmp

Download the Redmine source code:

curl -O https://www.redmine.org/releases/redmine-4.2.3.tar.gz

Extract it:

tar -xvvf redmine-4.2.3.tar.gz

Move the extracted code to /usr/share/redmine directory

sudo mv -v redmine-4.2.3 /usr/share/redmine

Switch to the /usr/share/redmine directory:

cd /usr/share/redmine/

Install bundler (a ruby dependency manager). We will have to install it as a super user since the ruby gems directory is owned by root:

sudo gem install bundler

Create a database config file from the provided template:

cp -v config/database.yml.example  config/database.yml

I will be using vim as my preferred command line text editor. You can use any alternative command line text editor, such as nano or emacs.

vi config/database.yml

Set the production YAML block as follows:

production:
  adapter: mysql2
  database: redmine_production
  host: localhost
  username: redmine_user
  password: "your_redmine_password"
  encoding: utf8

Save an close vim by entering :wq! on your terminal.

Install Redmine dependencies:

First, configure bundler to omit installing any of the gems used in test and development environments. Also, bundler should skip installing unnecessary gems such as postgresql and sqlite, which we aren’t using in this tutorial.

bundle config set --local without 'development test postgresql sqlite'

Install the Redmine ruby gems:

bundle install --without development test postgresql sqlite

Create a secret token to secure the HTML forms in Redmine against CSRF attacks:

bundle exec rails generate_secret_token

Create the Redmine database tables:

bundle exec rails db:migrate RAILS_ENV=production

Seed the database with default data, and set the language to be used to English (you can change this if English isn’t your preferred language).

bundle exec rails redmine:load_default_data RAILS_ENV=production REDMINE_LANG=en

Step 5: Integrate Redmine with Apache 2

As a security precaution, rename (or delete) the default Apache 2 index file before continuing:

sudo mv -v /var/www/html/index.html /var/www/html/index.html.bak

Remove the Apache 2 server signatures (that are usually listed on the default apache error pages). Edit the main Apache configuration file:

sudo vi /etc/apache2/apache2.conf

Add the following to the bottom of the file:

ServerTokens Prod
ServerSignature Off

Save the file and close vim then restart Apache:

sudo systemctl restart apache2

Create a Redmine Apache Virtual Host file (vhost):

sudo vi /etc/apache2/sites-available/redmine.conf

Add the following content to the vhost:

NB: Substitute your_domain with your own domain e.g. example.com

<VirtualHost *:80>
    ServerName www.your_domain
    ServerAlias your_domain
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/html
    RailsEnv  production

    Alias /redmine /usr/share/redmine/public
    <Location /redmine>
      PassengerBaseURI /redmine
      PassengerAppRoot /usr/share/redmine
    </Location>

    <Directory /usr/share/redmine/public>
      Allow from all
      Options -MultiViews
      Require all granted
    </Directory>

    <Directory /var/www/html>
        Allow from all
        Options -Indexes -MultiViews
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/error.log

    # Possible values include: debug, info, notice, warn, error, crit, alert, emerg.
    LogLevel warn

    CustomLog ${APACHE_LOG_DIR}/access.log combined
 </VirtualHost>

Check if your configuration file’s syntax is sound:

sudo apachectl configtest

If all is well, you should see:

Syntax OK

Disable the default Apache vhost:

sudo a2dissite 000-default

Enable the newly created Redmine vhost:

sudo a2ensite redmine

Reload Apache:

sudo systemctl reload apache2

On a web browser go to your_domain/redmine.

Redmine Home

Click on the ‘Sign in’ link on the top-right.

Redmine Login

Use the credentials admin/admin to login.

NB: You will thereafter be prompted to enter a new password. Please enter a more secure/strong password for the admin user.