How to Install and Configure Redmine on CentOS 8

Redmine is a free and open-source project management and issue tracking application. 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 explains how to install and configure the latest version of Redmine on CentOS 8. We’ll use MariaDB as a database back-end and Passenger + Apache as a Ruby application server.

Prerequisites #

Ensure that you have met the following prerequisites:

• Domain name pointing to your server public IP.
• You are logged in as root or user with sudo privileges .

Creating a MySQL database #

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

If you don’t have MariaDB or MySQL installed on your CentOS server, you can install it by following these instructions .

Login to the MySQL shell using the following command:

sudo mysql

From within the MySQL shell, run the following SQL statements to create a new database , new user, and grant the user access to the database :

CREATE DATABASE redmine CHARACTER SET utf8;
GRANT ALL ON redmine.* TO 'redmine'@'localhost' IDENTIFIED BY 'change-with-strong-password';

Once done, exit the MySQL shell:

EXIT;

Installing Passenger, Apache and Ruby #

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 Apache module.

Enable the EPEL repository :

sudo dnf install epel-release
sudo dnf config-manager --enable epel

Once the repository is enabled, update the packages list and install Ruby, Apache and Passenger:

sudo dnf install httpd mod_passenger passenger passenger-devel ruby

Start the Apache service and enable it to start on boot:

sudo systemctl enable httpd --now

Creating New System User #

Create a new user and group, with home directory /opt/redmine that will run the Redmine instance:

sudo useradd -m -U -r -d /opt/redmine redmine

Add the apache user to the redmine group and change the /opt/redmine directory permissions so that the Apache can access it:

sudo usermod -a -G redmine apache
sudo chmod 750 /opt/redmine

Installing Redmine #

At the time of writing, the latest stable version of Redmine is version 4.1.0.

Before continuing with the next steps, visit the Redmine download page to see if a newer version is available.

Install the GCC compiler and libraries required to build Redmine:

sudo dnf group install "Development Tools"
sudo dnf install zlib-devel curl-devel openssl-devel mariadb-devel ruby-devel

Make sure you are running the following steps as redmine user:

sudo su - redmine

1. Downloading Redmine #

Download the Redmine archive with curl :

curl -L https://www.redmine.org/releases/redmine-4.1.0.tar.gz -o redmine.tar.gz

Once the download is completed, extract the archive:

tar -xvf redmine.tar.gz

2. Configuring Redmine Database #

Copy the Redmine example database configuration file:

cp /opt/redmine/redmine-4.1.0/config/database.yml.example /opt/redmine/redmine-4.1.0/config/database.yml

Open the file with your text editor:

nano /opt/redmine/redmine-4.1.0/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: utf8mb4

Once done, save the file and exit the editor.

3. Installing Ruby dependencies #

Switch to the redmine-4.1.0 directory and install the Ruby dependencies:

cd ~/redmine-4.1.0
gem install bundler --no-rdoc --no-ri
bundle install --without development test postgresql sqlite --path vendor/bundle

4. Generate Keys and Migrate the Database #

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

bundle exec rake generate_secret_token
RAILS_ENV=production bundle exec rake db:migrate

Configuring Apache #

Switch back to your sudo user and create the following Apache vhost file:

exit
sudo nano /etc/httpd/conf.d/example.com.conf

<VirtualHost *:80>
    ServerName example.com
    ServerAlias www.example.com
    DocumentRoot /opt/redmine/redmine-4.1.0/public

    <Directory /opt/redmine/redmine-4.1.0/public>
        Options Indexes ExecCGI FollowSymLinks
        Require all granted
        AllowOverride all
    </Directory>

    ErrorLog /var/log/httpd/example.com-error.log
    CustomLog /var/log/httpd/example.com-access.log combined
</VirtualHost>

Restart the Apache service by typing:

sudo systemctl restart httpd

Configure Apache with SSL #

If you don’t have a trusted SSL certificate for your domain, you can generate a free Let’s Encrypt SSL certificate by following these instructions .

Once the certificate is generated, edit the Apache configuration as follows:

sudo nano /etc/httpd/conf.d/example.com.conf

<VirtualHost *:80>
  ServerName example.com
  ServerAlias www.example.com

  Redirect permanent / https://example.com/
</VirtualHost>

<VirtualHost *:443>
  ServerName example.com
  ServerAlias www.example.com

  Protocols h2 http/1.1

  <If "%{HTTP_HOST} == 'www.example.com'">
    Redirect permanent / https://example.com/
  </If>

  DocumentRoot /opt/redmine/redmine-4.1.0/public
  ErrorLog /var/log/httpd/example.com-error.log
  CustomLog /var/log/httpd/example.com-access.log combined

  SSLEngine On
  SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
  SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem

  <Directory /opt/redmine/redmine-4.1.0/public>
    Options Indexes ExecCGI FollowSymLinks
    Require all granted
    AllowOverride all
  </Directory>

</VirtualHost>

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 log in 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.

If you can’t access the page, then probably your firewall is blocking port Apache ports.

Use the following commands to open the necessary port:

sudo firewall-cmd --permanent --zone=public --add-port=443/tcp
sudo firewall-cmd --permanent --zone=public --add-port=80/tcp
sudo firewall-cmd --reload

Conclusion #

You have successfully installed Redmine on your CentOS 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.

About the authors

Dejan Panovski

Dejan Panovski is the founder of Linuxize, an RHCSA-certified Linux system administrator and DevOps engineer based in Skopje, Macedonia. Author of 800+ Linux tutorials with 20+ years of experience turning complex Linux tasks into clear, reliable guides.

View author page