How to Install Redmine on CentOS / RHEL 8 - CentLinux

Latest

Monday, 16 August 2021

How to Install Redmine on CentOS / RHEL 8

How to Install Redmine on CentOS / RHEL 8

Redmine is a free and open source project management software. In this guide, you will learn how to install Redmine on CentOS / RHEL 8.

 

Table of Contents:

 

What is Redmine? :

Redmine is a free and open source, web-based project management and issue tracking tool. It allows users to manage multiple projects and associated subprojects. It features per project wikis and forums, time tracking, and flexible, role-based access control. It includes a calendar and Gantt charts to aid visual representation of projects and their deadlines. Redmine integrates with various version control systems and includes a repository browser and diff viewer.

Redmine is written using the Ruby on Rails framework. It is cross-platform and cross-database and supports 49 languages. (Courtesy: Wikipedia)

Recommended Book: Mastering Redmine - Second Edition by Andriy Lesyuk

Recommended Training: Project Management Essentials: Ace Your Next Project!

 

Environment Specification:

We are using a minimal Red Hat Enterprise Linux 8 virtual machine with following specifications.

  • CPU - 3.4 Ghz (2 cores)
  • Memory - 2 GB
  • Storage - 20 GB
  • Operating System - RHEL 8.4
  • Hostname – redmine-01.centlinux.com
  • IP Address - 192.168.116.238/24

 

Update Linux Software Packages:

By using a ssh client, connect with Linux server as root user.

By following the best practice, update software packages in your Linux operating system before installing Redmine project management tool.

# dnf update -y

If the above command updates your Linux Kernel then you should restart your operating system with the newly installed kernel.

# reboot

Check the Linux Kernel version on your machine.

# uname -r
4.18.0-305.12.1.el8_4.x86_64

Check the version of your Linux operating system.

# cat /etc/redhat-release
Red Hat Enterprise Linux release 8.4 (Ootpa)

 

Create Linux User for Redmine:

Here, we are installing Redmine project management software in /opt/redmineuser.

Therefore, create a Linux user and set /opt/redmineuser as its home directory.

# useradd -r -m -d /opt/redmineuser redmineuser

Set the password for redmineuser.

# passwd redmineuser

Grant sudo privilege to redmineuser, required for executing bundle commands.

# usermod -aG wheel redmineuser

 

Install Apache Web Server on CentOS / RHEL 8:

Redmine software requires a web server to deploy it's application. Therefore, execute dnf command and install Apache on your Linux server.

# dnf install -y httpd

Enable and start Apache web server.

# systemctl enable --now httpd.service
Created symlink /etc/systemd/system/multi-user.target.wants/httpd.service → /usr/lib/systemd/system/httpd.service.

Grant redmineuser group to apache user, so it have necessary access to the files in /opt/redmineuser directory.

# usermod -aG redmineuser apache

 

Install MySQL Database Server:

Redmine software currently supports PostgreSQL and MySQL databases. Here, we are using a MariaDB database server and configure it as the backend for the Project management application.

You can follow our previous post to install MariaDB database on CentOS / RHEL 8.

Connect with MySQL database instance as root user.

# mysql -u root -p

Execute following commands at MySQL shell to create a database and user for Redmine software.

MariaDB [(none)]> create database redminedb;
Query OK, 1 row affected (0.001 sec)

MariaDB [(none)]> grant all on redminedb.* to redmineadmin@localhost identified by 'P@ssw0rd';
Query OK, 0 rows affected (0.001 sec)

MariaDB [(none)]> flush privileges;
Query OK, 0 rows affected (0.001 sec)

MariaDB [(none)]> quit
Bye

 

Install EPEL Repository on CentOS / RHEL 8:

Some of the prerequisite packages of Redmine software are not available in standard yum repositories, therefore, you need to install EPEL yum repository on your Linux server.

The procedure of installing EPEL is little bit different on CentOS and RHEL operating systems.

Execute the following commands to install EPEL on CentOS 8 and enable the required repo.

# dnf install -y epel-release

# dnf config-manager --set-enabled PowerTools

Execute the following commands to install EPEL on RHEL 8 and enable the required repo.

# dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

# subscription-manager repos --enable "codeready-builder-for-rhel-8-x86_64-rpms"
Repository 'codeready-builder-for-rhel-8-x86_64-rpms' is enabled for this system.

Build cache for newly added yum repositories.

# dnf makecache
Updating Subscription Management repositories.
Extra Packages for Enterprise Linux Modular 8 - 6.6 kB/s | 9.4 kB     00:01
Extra Packages for Enterprise Linux 8 - x86_64  5.2 kB/s | 5.7 kB     00:01
Red Hat Enterprise Linux 8 for x86_64 - BaseOS  2.6 kB/s | 4.1 kB     00:01
Red Hat CodeReady Linux Builder for RHEL 8 x86_ 201 kB/s | 5.4 MB     00:27
Red Hat Enterprise Linux 8 for x86_64 - AppStre 3.5 kB/s | 4.5 kB     00:01
Metadata cache created.

 

Install Redmine Prerequisites:

If you have setup the yum repositories as per above steps then you can easily install all the prerequisites with a single dnf command.

# dnf install -y ruby ruby-devel rpm-build wget libxml2-devel make automake libtool ImageMagick ImageMagick-devel mariadb-devel httpd-devel openssl-devel libcurl-devel gcc gcc-c++

Check the version of your installed ruby.

# ruby -v
ruby 2.5.9p229 (2021-04-05 revision 67939) [x86_64-linux]

 

Configure Linux Firewall:

Redmine is written in Ruby programming language. And the default port for Ruby web server is 3000/tcp.

Therefore, you need to add this port in Linux firewall, to make your application accessible across the network.

# firewall-cmd --add-port=3000/tcp --permanent
Success
# firewall-cmd --reload
Success

 

Install Redmine Project Management Software:

Switch to redmineuser to start installation of your project management software.

# su - redmineuser

Go to https://www.redmine.org/projects/redmine/wiki/download and copy the URL of latest stable release of Redmine software.

Then use wget command to download Redmine setup.

$ wget https://www.redmine.org/releases/redmine-4.2.2.tar.gz
--2021-08-14 11:53:15--  https://www.redmine.org/releases/redmine-4.2.2.tar.gz
Resolving www.redmine.org (www.redmine.org)... 46.4.101.126
Connecting to www.redmine.org (www.redmine.org)|46.4.101.126|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 3038398 (2.9M) [application/x-gzip]
Saving to: ‘redmine-4.2.2.tar.gz’

redmine-4.2.2.tar.g 100%[===================>]   2.90M  26.7KB/s    in 2m 6s

2021-08-14 11:55:23 (23.5 KB/s) - ‘redmine-4.2.2.tar.gz’ saved [3038398/3038398]

Extract downloaded zip file to /opt/redmineuser directory by using following command.

$ tar xzf redmine-4.2.2.tar.gz -C /opt/redmineuser/ --strip-components=1

Create Redmine configuration files by using the vendor supplied examples.

$ cd /opt/redmineuser/
$ cp config/configuration.yml.example config/configuration.yml
$ cp config/database.yml.example config/database.yml
$ cp public/dispatch.fcgi.example public/dispatch.fcgi

Edit database.yml file in vim text editor.

$ vi config/database.yml

Find and configure your database connection settings under following section.

production:
  adapter: mysql2
  database: redminedb
  host: localhost
  username: redmineadmin
  password: "P@ssw0rd"
  # Use "utf8" instead of "utfmb4" for MySQL prior to 5.7.7
  encoding: utf8mb4

Execute following gem command to install bundler for managing ruby gem dependencies.

$ gem install bundler
Fetching: bundler-2.2.25.gem (100%)
Successfully installed bundler-2.2.25
Parsing documentation for bundler-2.2.25
Installing ri documentation for bundler-2.2.25
Done installing documentation for bundler after 7 seconds
1 gem installed

Set the environment and install gem dependencies as follows.

$ bundle config set --local without 'development test'
$ bundle install
...
Fetching roadie-rails 2.2.0
Installing rails 5.2.6
Installing roadie-rails 2.2.0
Bundle complete! 37 Gemfile dependencies, 63 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.

If you face conflicts in gems versions then you can execute following command to restore gems to pristine state.

$ sudo gem pristine --all

To prevent tampering of the cookies that stores session data, you are required to generate a random secret key.

$ bundle exec rake generate_secret_token

Create database structure by executing following command.

$ RAILS_ENV=production bundle exec rake db:migrate
...
== 20190510070108 AddUniqueIdToImportItems: migrating =========================
-- change_table(:import_items)
   -> 0.0082s
== 20190510070108 AddUniqueIdToImportItems: migrated (0.0085s) ================

== 20190620135549 ChangeRolesNameLimit: migrating =============================
-- change_column(:roles, :name, :string, {:limit=>255, :default=>""})
   -> 0.0035s
== 20190620135549 ChangeRolesNameLimit: migrated (0.0037s) ====================

== 20200826153401 AddTwofaSchemeToUser: migrating =============================
-- add_column(:users, :twofa_scheme, :string)
   -> 0.0032s
== 20200826153401 AddTwofaSchemeToUser: migrated (0.0034s) ====================

== 20200826153402 AddTotpToUser: migrating ====================================
-- add_column(:users, :twofa_totp_key, :string)
   -> 0.0024s
-- add_column(:users, :twofa_totp_last_used_at, :integer)
   -> 0.0026s
== 20200826153402 AddTotpToUser: migrated (0.0052s) ===========================

Insert default configuration data into the MySQL database.

$ RAILS_ENV=production REDMINE_LANG=en bundle exec rake redmine:load_default_data
Default configuration data loaded.

Create necessary directories and adjust file permissions.

$ mkdir -p tmp/pdf
$ mkdir -p public/plugin_assets
$ chown -R redmineuser:redmineuser files log tmp public/plugin_assets
$ chmod -R 755 /opt/redmineuser/

Execute the following command to start a Rails server instance by using WEBrick.

$ bundle exec rails server webrick -e production
...
=> Booting WEBrick
=> Rails 5.2.6 application starting in production on http://0.0.0.0:3000
=> Run `rails server -h` for more startup options
[2021-08-14 14:57:49] INFO  WEBrick 1.4.2.1
[2021-08-14 14:57:49] INFO  ruby 2.5.9 (2021-04-05) [x86_64-linux]
[2021-08-14 14:57:49] INFO  WEBrick::HTTPServer#start: pid=3545 port=3000

Open URL http://192.168.116.238:3000/login in a web browser.

Login with default credentials i.e. admin/admin.

01-redmine-web-ui-login

Since, you are login for the first time, therefore you may be asked to change the password.

02-redmine-change-password

After changing your password, you will be redirected to the “My Account” page.

03-redmine-my-account-page

Redmine project management software has been installed successfully.

 

Install Phusion Passenger on CentOS / RHEL 8:

Phusion Passenger is a ruby application server that can be used to serve Redmine via Apache web server.

You can install Passenger by using following gem command.

$ gem install passenger --no-rdoc --no-ri
Fetching: passenger-6.0.10.gem (100%)
Building native extensions. This could take a while...
Successfully installed passenger-6.0.10
1 gem installed

Install Passenger module on Apache web server.

$ passenger-install-apache2-module

During execution of above command, you are asked to create following configuration files.

04-phusion-passenger-apache-module

05-phusion-passenger-apache-conf

Therefore, open another ssh session as root user and perform following configurations.

Create an Apache module configuration file by using vim text editor.

# vi /etc/httpd/conf.modules.d/00-passenger.conf

Add following directives in this file.

LoadModule passenger_module /opt/redmineuser/.gem/ruby/gems/passenger-6.0.10/buildout/apache2/mod_passenger.so
   <IfModule mod_passenger.c>
     PassengerRoot /opt/redmineuser/.gem/ruby/gems/passenger-6.0.10
     PassengerDefaultRuby /usr/bin/ruby
   </IfModule>

Create an Apache configuration file by using vim text editor.

# vi /etc/httpd/conf.d/redmine.conf

Add following directives in this file.

Listen 3000
<IfModule mod_passenger.c>
  PassengerRoot /opt/redmineuser/.gem/ruby/gems/passenger-6.0.10
  PassengerDefaultRuby /usr/bin/ruby
</IfModule>
<VirtualHost *:3000>
    ServerName redmine-01.centlinux.com
    DocumentRoot "/opt/redmineuser/public" 

    CustomLog logs/redmine_access.log combined
    ErrorLog logs/redmine_error_log
    LogLevel warn

    <Directory "/opt/redmineuser/public">
        Options Indexes ExecCGI FollowSymLinks
        Require all granted
        AllowOverride all
    </Directory>
</VirtualHost>

Verify the Apache configurations by executing following command.

# httpd -t
Syntax OK

Continue and finish Passenger installation.

Restart Apache service to load changes.

# systemctl restart httpd.service

Passenger installation with gems command does not provide a SELinux configuration.

Therefore, you have to disable SELinux on your Linux server.

# setenforce 0
# sed -i s/^SELINUX=.*$/SELINUX=disabled/ /etc/selinux/config

Open URL http://192.168.116.238:3000/login in a web browser.

01-redmine-web-ui-login

 

Conclusion:

In this guide, you have learned how to install redmine on CentOS / RHEL 8. You can now start experimenting with this project management software to explore its features and functionality.

No comments:

Post a Comment