How to Install and Configure Redmine on Ubuntu 18.04

Redmine is one of the most popular open-source project management and issue tracking software tools. It is cross-platform and cross-database and built on top of the Ruby on Rails framework.

Redmine includes support for multiple projects, wikis, issue tracking system, forums, calendars, email notifications, and much more.

This tutorial describes how to install and configure the latest version of Redmine on an Ubuntu 18.04 server using MySQL as a database back-end and Passenger + Nginx as a Ruby application server.

Prerequisites #

Make sure that you have met the following prerequisites before continuing with this tutorial:

• You have a domain name pointing to your server public IP. In this tutorial we will use example.com.
• You are logged in as a user with sudo privileges .
• You have Nginx installed by following these instructions .
• You have a SSL certificate installed for your domain. You can install a free Let’s Encrypt SSL certificate by following these instructions .

Creating MySQL database #

Redmine supports MySQL/MariaDB, Microsoft SQL Server, SQLite 3 and PostgreSQL . In this tutorial we’ll use MySQL as a database back-end.

If you already don’t have MySQL installed on your Ubuntu server you can install by following these instructions .

Login to the MySQL shell by typing the following command:

sudo mysql

From within the MySQL shell, run the following SQL statement to create a new database :

CREATE DATABASE redmine CHARACTER SET utf8mb4;

Next, create a MySQL user account and grant access to the database :

GRANT ALL ON redmine.* TO 'redmine'@'localhost' IDENTIFIED BY 'change-with-strong-password';

Once done, exit the mysql console by typing:

EXIT;

Installing Ruby #

The easiest way to install Ruby on your Ubuntu system is through the apt package manager. At the time of writing, the version in the Ubuntu repositories is 2.5.1 which is the latest stable version of Ruby.

Install Ruby by typing:

sudo apt install ruby-full

If you want to install Ruby via Rbenv or RVM check this guide .

Installing Passenger and Nginx #

Passenger is a fast and lightweight web application server for Ruby, Node.js and Python that can be integrated with Apache and Nginx. We will install Passenger as an Nginx module.

Make sure you followed the prerequisites and installed Nginx before continuing with the following steps.

Start by installing the necessary packages:

sudo apt install dirmngr gnupg apt-transport-https ca-certificates

Import the repository GPG key and enable the Phusionpassenger repository:

sudo apt-key adv --recv-keys --keyserver hkp://keyserver.ubuntu.com:80 561F9B9CAC40B2F7sudo add-apt-repository 'deb https://oss-binaries.phusionpassenger.com/apt/passenger bionic main'

Once the apt repository is enabled , update the packages list and install the Passenger Nginx module with:

sudo apt updatesudo apt install libnginx-mod-http-passenger

Installing Redmine on Ubuntu #

We’ll start by installing the dependencies necessary to build Redmine:

sudo apt install build-essential libmysqlclient-dev imagemagick libmagickwand-dev

At the time of writing this article, the latest stable version of Redmine is version 4.0.0.

Before continuing with the next step you should check the Redmine download page to see if a newer version is available.

1. Downloading Redmine #

Download the Redmine archive with the following curl command :

sudo curl -L http://www.redmine.org/releases/redmine-4.0.0.tar.gz -o /tmp/redmine.tar.gz

Once the download is completed extract the archive and move it to the /opt directory:

cd /tmpsudo tar zxf /tmp/redmine.tar.gzsudo mv /tmp/redmine-4.0.0 /opt/redmine

2. Configuring Redmine Database #

Start by copying the Redmine example configuration file:

sudo cp /opt/redmine/config/database.yml.example /opt/redmine/config/database.yml

Open the file with your text editor:

sudo nano /opt/redmine/config/database.yml

Search for the production section and enter the MySQL database and user information we created previously:

production:
  adapter: mysql2
  database: redmine
  host: localhost
  username: redmine
  password: "change-with-strong-password"
  encoding: utf8

Once done, save the file and exit the editor.

3. Installing Ruby dependencies #

Navigate to the redmine directory and install bundler and other Ruby dependencies:

cd /opt/redmine/sudo gem install bundler --no-rdoc --no-ri sudo bundle install --without development test postgresql sqlite

4. Generate Keys and Migrate the Database #

Run the following command to generate keys and migrate the database:

cd /opt/redmine/sudo bundle exec rake generate_secret_tokensudo RAILS_ENV=production bundle exec rake db:migrate

5. Set the correct Permissions #

Nginx runs as www-data user and group. Set the correct permissions by issuing following chown command :

sudo chown -R www-data: /opt/redmine/

Configure Nginx #

By now, you should already have Nginx with SSL certificate installed on your system, if not check the prerequisites for this tutorial.

Open your text editor and create the following Nginx server block file:

sudo nano /etc/nginx/sites-available/example.com

# Redirect HTTP -> HTTPS
server {
    listen 80;
    server_name www.example.com example.com;

    include snippets/letsencrypt.conf;
    return 301 https://example.com$request_uri;
}

# Redirect WWW -> NON WWW
server {
    listen 443 ssl http2;
    server_name www.example.com;

    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.pem;
    include snippets/ssl.conf;

    return 301 https://example.com$request_uri;
}

server {
    listen 443 ssl http2;
    server_name example.com;

    root /opt/redmine/public;

    # SSL parameters
    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.pem;
    include snippets/ssl.conf;
    include snippets/letsencrypt.conf;

    # log files
    access_log /var/log/nginx/example.com.access.log;
    error_log /var/log/nginx/example.com.error.log;

    passenger_enabled on;
    passenger_min_instances 1;
    client_max_body_size 10m;
}

Enable the server block by creating a symbolic link to the sites-enabled directory:

sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/

Before restarting the Nginx service make a test to be sure that there are no syntax errors:

sudo nginx -t

If there are no errors the output should look like this:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Finally, restart the Nginx service by typing:

sudo systemctl restart nginx

Accessing Redmine #

Open your browser , type your domain and assuming the installation is successful, a screen similar to the following will appear:

The default login credentials for Redmine are:

• Username: admin
• Password: admin

When you login for the first time, you will be prompted to change the password as shown below:

Once you change the password you will be redirected to the user account page.

Conclusion #

You have successfully installed Redmine on your Ubuntu system. You should now check the Redmine Documentation and learn more about how to configure and use Redmine.

If you hit a problem or have feedback, leave a comment below.