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.

Redmine supports multiple database servers for storing the database. It is a feature-rich application supporting multiple projects, role based ACL and issue tracking system. It also has Gantt chart and calendar support, file management, per project wiki and forum, as well as many other features. It supports version control systems such as Git, SVN or CVS. It is also multilingual, supporting as many as 49 languages.

This guide was written for Redmine 4.0.2, but may apply to newer versions as well.

Assumptions

  • CentOS 7 is installed and works
  • Your are logged as root
  • The next steps are done successively without errors
  • A domain name pointed towards the server.

For this tutorial, we will use 192.168.1.1 as the public IP address and redmine.yourdomain.com as the domain name pointed towards the guterplus instance. Please make sure to replace all occurrences of the example domain name and IP address with the actual one.

Install Apache

Redmine is written in Ruby on Rails, thus we will require Phusion Passenger to integrate with the Apache web server to serve the application. Install Apache.

sudo yum -y install httpd httpd-devel libcurl-devel
To build the Redmine application, we will need some development tools as well. Install the required tools.

sudo yum -y install ImageMagick ImageMagick-devel git libxml2-devel libxslt-devel gcc bzip2 openssl-devel zlib-devel gdbm-devel ncurses-devel autoconf automake bison gcc-c++ libffi-devel libtool patch readline-devel sqlite-devel glibc-headers glibc-devel libyaml-devel libicu-devel libidn-devel

Install PostgreSQL

Redmine supports multiple types of database servers such as MySQL, PostgreSQL, and MSSQL. In this tutorial, we will use PostgreSQL to host the Redmine database server.

PostgreSQL is an object-relational database system. The default yum repository contains an old version of PostgreSQL, so add the PostgreSQL repository to the system.

sudo yum -y install https://download.postgresql.org/pub/repos/yum/10/redhat/rhel-7-x86_64/pgdg-centos10-10-1.noarch.rpm
Install the PostgreSQL database server.

sudo yum -y install postgresql10-server postgresql10-contrib postgresql10
Initialize the database.

sudo /usr/pgsql-10/bin/postgresql-10-setup initdb
Start the PostgreSQL server and enable it to start automatically at boot time.

sudo systemctl start postgresql-10
sudo systemctl enable postgresql-10
Change the password for the default PostgreSQL user.

sudo passwd postgres
Log in as the PostgreSQL user.

sudo su - postgres
Create a new PostgreSQL user for Redmine.

createuser redmine

You are allowed to use any username instead of redmine. PostgreSQL provides the psql shell to run queries on the database. Switch to the PostgreSQL shell.

psql

Set a password for the newly created user for the Redmine database.

ALTER USER redmine WITH ENCRYPTED password 'DBPassword';
Replace DBPassword with a secure password. Create a new database for the Redmine installation.

CREATE DATABASE redmine WITH ENCODING='UTF8' OWNER=redmine;
Exit from the psql shell.

\q
Switch to the sudo user.

exit
Edit the pg_hba.conf file to enable MD5 based authentication.

sudo nano /var/lib/pgsql/10/data/pg_hba.conf
Find the following lines and change the values peer and ident in the METHOD column to trust and md5, respectively.

# TYPE DATABASE USER ADDRESS METHOD

# “local” is for Unix domain socket connections only
local all all peer
# IPv4 local connections:
host all all 127.0.0.1/32 ident
# IPv6 local connections:
host all all ::1/128 ident
Once updated, the configuration should look like this.

# TYPE DATABASE USER ADDRESS METHOD

# “local” is for Unix domain socket connections only
local all all trust
# IPv4 local connections:
host all all 127.0.0.1/32 md5
# IPv6 local connections:
host all all ::1/128 md5
Restart PostgreSQL so that the changes can take effect.

sudo systemctl restart postgresql-10
Install a few more required PostgreSQL dependencies.

sudo yum -y install libpqxx-devel protobuf-devel

Install Ruby

It is recommended to use an unprivileged user to run the application to keep it isolated from rest of the system. Create a new user for Redmine and switch to the newly created user.

sudo adduser redmine
sudo su - redmine
We will install the latest version of Ruby using Ruby Version Manager, or RVM. It is used to install and manage multiple versions of Ruby.

Add the GPG key of RVM to your server.

gpg --keyserver hkp://keys.gnupg.net --recv-keys 509B6B1796C275463B6703113804DD82D39DC7U3 7D2BAF1CF37B13E2069D6956105BD0E739499BDD

Install RVM.

curl -sSL https://get.rvm.io | bash -s stable
source ~/.rvm/scripts/rvm

Fetch the list of the available versions of Ruby.

rvm list known

You will see a long list of Ruby versions.

[[email protected] ~]$ rvm list known
# MRI Rubies
[ruby-]1.8.6[-p420]
[ruby-]1.8.7[-head] # security released on head
[ruby-]1.9.1[-p431]
[ruby-]1.9.2[-p330]
[ruby-]1.9.3[-p551]
[ruby-]2.0.0[-p648]
[ruby-]2.1[.10]
[ruby-]2.2[.10]
[ruby-]2.3[.8]
[ruby-]2.4[.6]
[ruby-]2.5[.5]
[ruby-]2.6[.3]
ruby-head

...
Install the latest version of Ruby from the list.

rvm install 2.6

Use the installed version of Ruby.

rvm use 2.6

You can verify its version.

ruby -v

You will see a similar output.

[[email protected] ~]$ ruby -v
ruby 2.6.3p62 (2019-04-16 revision 67580) [x86_64-linux]

Install bundler, which is the dependency manager for the Ruby application.

gem install bundler

Ruby is now installed. Before we install Redmine, we will need to install Phusion Passenger.

Install Passenger

Run the following command to install Passenger.

gem install passenger

Provide execution permission to the home directory of redmine user. Passenger needs to execute the binaries in order to serve the application.

chmod o+x "/home/redmine"

Install the Apache module for Passenger.

passenger-install-apache2-module

The installer script will ask you some questions. First, it will provide you information about the installation process. Then it will ask you to select the language which you will be using. Since our application is written in Ruby on Rails, select Ruby from the menu and press “Enter” to proceed further.

Which languages are you interested in?

Use <space> to select.
If the menu doesn't display correctly, press '!'

‣ ⬢ Ruby
⬡ Python
⬡ Node.js
⬡ Meteor

The installer will now check for requirements. The installer will not encounter any missing dependencies and will automatically proceed to compile and install the module.

Once the module is installed, it will prompt you to add the module into the Apache configuration file.

Almost there!

Please edit your Apache configuration file, and add these lines:

LoadModule passenger_module /home/redmine/.rvm/gems/ruby-2.6.3/gems/passenger-6.0.2/buildout/apache2/mod_passenger.so
<IfModule mod_passenger.c>
PassengerRoot /home/redmine/.rvm/gems/ruby-2.6.3/gems/passenger-6.0.2
PassengerDefaultRuby /home/redmine/.rvm/gems/ruby-2.6.3/wrappers/ruby
</IfModule>

After you restart Apache, you are ready to deploy any number of web
applications on Apache, with a minimum amount of configuration!

Press ENTER when you are done editing.
We will skip this for now and will complete it later in the tutorial as the user with which we are logged in now does not have sudo permissions. Press “Enter” to skip this step.

Finally, the installer script will validate the installation and you will see a warning saying the Passenger module is not specified in Apache configuration.

Validating installation...

* Checking whether this Passenger install is in PATH... ✓
* Checking whether there are no other Passenger installations... ✓
* Checking whether Apache is installed... ✓
* Checking whether the Passenger module is correctly configured in Apache... (!)

You did not specify 'LoadModule passenger_module' in any of your Apache
configuration files. Please paste the configuration snippet that this
installer printed earlier, into one of your Apache configuration files, such
as /etc/httpd/conf/httpd.conf.

Detected 0 error(s), 1 warning(s).
Press ENTER to continue.
Now that we have installed the Passenger module for Apache, proceed to download and install Redmine.

Install Redmine

Download the latest version of Redmine from the official Redmine download page.

cd ~
wget http://www.redmine.org/releases/redmine-4.0.2.tar.gz

Extract the archive and rename the directory for sake of convenience.

tar -xf redmine-*.tar.gz
mv redmine-*/ redmine/

Copy the example configuration files to its production location.

cd redmine
cp config/configuration.yml.example config/configuration.yml
cp config/database.yml.example config/database.yml

Open the database configuration file we just copied to enter the database details.

nano config/database.yml

By default, the database file is configured for MySQL. Find the configurations for production and development, and test which uses the MySQL adapter. Comment out all of these lines.

#production:
# adapter: mysql2
# database: redmine
# host: localhost
# username: root
# password: ""
# encoding: utf8

#development:
# adapter: mysql2
# database: redmine_development
# host: localhost
# username: root
# password: ""
# encoding: utf8

#test:
# adapter: mysql2
# database: redmine_test
# host: localhost
# username: root
# password: ""
# encoding: utf8

Furthur, find the lines which are commented, having production configuration for the postgresql adapter. Uncomment those lines and update the database name and user credentials. Make sure to use the correct indentation, which is two spaces.

production:
adapter: postgresql
database: redmine
host: localhost
username: redmine
password: "DBPassword"

 

Configure the application to use the PostgreSQL configuration.

bundle config build.pg --with-pg-config=/usr/pgsql-10/bin/pg_config

Install the application dependencies required by the application.

bundle install --without development test

You will see the following message at the end of the installation.

Installing roadie-rails 1.1.1
Bundle complete! 31 Gemfile dependencies, 55 gems now installed.
Gems in the groups development and test were not installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.

The following command generates secret tokens that are used to encode the session data.

bundle exec rake generate_secret_token

Write the PostgreSQL database.

RAILS_ENV=production bundle exec rake db:migrate

Run the following command, which writes the default data into PostgreSQL database.

RAILS_ENV=production bundle exec rake redmine:load_default_data
The above command will ask you to choose the default language to be used with the application. The default choice is English; choose according to your preference.

[[email protected] redmine]$ RAILS_ENV=production bundle exec rake redmine:load_default_data

Select language: ar, az, bg, bs, ca, cs, da, de, el, en, en-GB, es, es-PA, et, eu, fa, fi, fr, gl, he, hr, hu, id, it, ja, ko, lt, lv, mk, mn, nl, no, pl, pt, pt-BR, ro, ru, sk, sl, sq, sr, sr-YU, sv, th, tr, uk, vi, zh, zh-TW [en]
====================================
Default configuration data loaded.

Installation of the Redmine application is now finished. Change ownership and permissions of the directories and files.

mkdir -p tmp tmp/pdf public/plugin_assets
chown -R redmine:redmine files log tmp public/plugin_assets
chmod -R 755 files log tmp public/plugin_assets

We have configured everything we need from the non-privileged user. Switch back to the sudo user by running su - <username>.

Configure Apache

Add the Passenger module for Apache into the Apache configuration file. This will automatically load the Passenger module.

echo "LoadModule passenger_module /home/redmine/.rvm/gems/ruby-2.6.3/gems/passenger-6.0.2/buildout/apache2/mod_passenger.so" | sudo tee -a /etc/httpd/conf.modules.d/00-base.conf

Create a new virtual host file for your Redmine application.

sudo nano /etc/httpd/conf.d/redmine.conf

Populate the file with the following content.

<VirtualHost *:80>
  ServerName tracker.yourdomain.com

  DocumentRoot /home/redmine/redmine/public
  <IfModule mod_passenger.c>
    PassengerRoot /home/redmine/.rvm/gems/ruby-2.6.3/gems/passenger-6.0.2
    PassengerRuby /home/redmine/.rvm/gems/ruby-2.6.3/wrappers/ruby
    PassengerUser redmine
  </IfModule>

  <Directory /home/redmine/redmine/public>
    Allow from all
    Options -MultiViews
    Require all granted
  </Directory>
</VirtualHost>

Make sure to replace redmine.yourdomain.com with your actual domain name. Also, make sure that the path to the PassengerRoot and PassengerRuby are correct. The path to the binaries may change when there is a new release of Ruby or Passenger. To find these paths, run the following command.

sudo su redmine -c "passenger-config about ruby-command"

You will get following output.

[[email protected] ~]$ sudo su redmine -c "passenger-config about ruby-command"
passenger-config was invoked through the following Ruby interpreter:
Command: /home/redmine/.rvm/gems/ruby-2.6.3/wrappers/ruby
Version: ruby 2.6.3p62 (2019-04-16 revision 67580) [x86_64-linux]
To use in Apache: PassengerRuby /home/redmine/.rvm/gems/ruby-2.6.3/wrappers/ruby
To use in Nginx : passenger_ruby /home/redmine/.rvm/gems/ruby-2.6.3/wrappers/ruby
To use with Standalone: /home/redmine/.rvm/gems/ruby-2.6.3/wrappers/ruby /home/redmine/.rvm/gems/ruby-2.6.3/gems/passenger-6.0.2/bin/passenger start

Once the Virtual host file is created, restart the Apache web server.

sudo systemctl restart httpd

Modify the firewall configuration to allow port 80 through the firewall.

sudo firewall-cmd --zone=public --add-service=http --permanent
sudo firewall-cmd --reload

You can now access your Redmine interface on http://redmine.yourdomain.com. Login with username admin and password admin. On your first login, Redmine will prompt you to update the password.