How to Install and Configure Redmine on CentOS 7

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.

In this tutorial we will cover the steps needed to install and configure the latest version of Redmine on a CentOS 7 server using MariaDB 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:

• Domain name pointing to your server public IP. In this tutorial we will use example.com.
• Logged in as a user with sudo privileges .

Install the packages required for building Redmine and Ruby from source:

sudo yum install curl gpg gcc gcc-c++ make patch autoconf automake bison libffi-devel libtool  
sudo yum install readline-devel sqlite-devel zlib-devel openssl-develh readline  glibc-headers glibc-devel
sudo yum install mariadb-devel zlib libyaml-devel bzip2 iconv-devel ImageMagick ImageMagick-devel

Creating MySQL database #

Redmine supports MySQL/MariaDB, Microsoft SQL Server, SQLite 3 and PostgreSQL . In this tutorial 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 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 utf8;

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 complete, exit the mysql shell by typing:

EXIT;

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.

Install the EPEL repository and the required packages:

sudo yum install epel-release yum-utils pygpgme
sudo yum-config-manager --enable epel

Enable the Phusionpassenger repository:

sudo yum-config-manager --add-repo https://oss-binaries.phusionpassenger.com/yum/definitions/el-passenger.repo

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

sudo yum install nginx passenger passenger-devel

Creating New System User #

Create a new user and group, which will run the Redmine instance, for simplicity we will name the user redmine:

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

Add the nginx user to the new user group and change the /opt/redmine directory permissions so that the Nginx can access it:

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

Installing Ruby #

The version of Ruby in the CentOS repositories is pretty outdated and not supported by Redmine. We’ll install Ruby using RVM.

Switch to the user redmine by typing:

sudo su - redmine

Import the GPG keys and install RVM:

gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
curl -sSL https://get.rvm.io | bash -s stable

To start using RVM source the rvm file:

source /opt/redmine/.rvm/scripts/rvm

Now we can install Ruby by running:

rvm install 2.5
rvm --default use 2.5

Installing Redmine on CentOS #

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

Before continuing with the next steps 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 :

curl -L https://www.redmine.org/releases/redmine-4.0.1.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.0.1/config/database.yml.example /opt/redmine/redmine-4.0.1/config/database.yml

Open the file with your text editor:

nano /opt/redmine/redmine-4.0.1/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-4.0.1 directory and install bundler and other Ruby dependencies:

cd ~/redmine-4.0.1
gem install bundler --no-rdoc --no-ri
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:

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

Configuring Nginx #

Switch back to your sudo user:

exit

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

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

passenger_root /usr/share/ruby/vendor_ruby/phusion_passenger/locations.ini;
passenger_ruby /opt/redmine/.rvm/gems/default/wrappers/ruby;
passenger_instance_registry_dir /var/run/passenger-instreg;

server {
    listen 80;
    server_name example.com www.example.com;

    root /opt/redmine/redmine-4.0.1/public;

    # 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;
}

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

Configure Nginx 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 domain Nginx configuration as follows:

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

passenger_root /usr/share/ruby/vendor_ruby/phusion_passenger/locations.ini;
passenger_ruby /opt/redmine/.rvm/gems/default/wrappers/ruby;
passenger_instance_registry_dir /var/run/passenger-instreg;

# 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/redmine-4.0.1/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;
}

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 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