Redmine is a popular open source project management web application. It supports mayor databases like MySQL and PostgreSQL as backend, and you can also change the frontend to Apache from the WEBrick (recommended for production use) webserver shipped with the installation. In this article we will install the latest Redmine on RHEL 8 / CentOS 8, using PostgreSQL as backend, but we will leave the default WEBrick as frontend, which will serve our tests perfectly.
Do not expect this process to be an easy one, nor error-free. Even following these steps to the letter, some errors will surely happen, the setup seem to handle
sudo steps somewhat inconsistently – but the solutions are also included which will guide trough these errors.
In this tutorial you will learn:
- How to install required operating system packages
- How to setup the database
- How to install the Redmine application
- How to start and login to the application
Software Requirements and Conventions Used
|Category||Requirements, Conventions or Software Version Used|
|System||RHEL 8 / CentOS 8|
|Software||Redmine 4.0.3, PostgreSQL 10.5|
|Other||Privileged access to your Linux system as root or via the
# – requires given linux commands to be executed with root privileges either directly as a root user or by use of
$ – requires given linux commands to be executed as a regular non-privileged user
How to install redmine on Redhat 8 step by step instructions
Redmine is a Ruby application. For the installation we’ll have to use
bundler, and compile a lot of dependencies, so it will take a while. We’ll use the Red Hat repositories available after enabling subscription management to solve the operating system dependencies. You can refer to the PostgreSQL installation guide on RHEL8 for the detailed setup of the database in general, in this article we’ll cover only the steps needed for Redmine. If the database setup is new, don’t forget to complete the
initdb step in the mentioned guide, or the startup of the database will fail.
- We’ll create a user who will be the owner of the application, and we’ll give it temporary
sudoaccess. We can revoke this access once the installation is complete.
# useradd redmine
We have to set a password for the new user, which we will use when using
# passwd redmine
On RHEL based distributions, there is a
wheeluser group, who is allowed to use
sudoto run privileged commands. To check that this group is set up as
sudoer, we can
# grep "%wheel" /etc/sudoers %wheel ALL=(ALL) ALL # %wheel ALL=(ALL) NOPASSWD: ALL
The second line with the NOPASSWD option is commented out, which will suit our needs. With the above configuration in place, all we need to do is add the
redmineuser to the
# usermod -a -G wheel redmine
- To install the packages the operating system will provide, we’ll use
# dnf install kernel-devel kernel-headers gcc postgresql-devel ruby ruby-devel rubygems
- To obtain the application, visit the the official download site (which is running on Redmine). From here we can download the compressed
wgetto the target system:
# wget https://www.redmine.org/releases/redmine-4.0.3.tar.gz -O /opt/redmine-4.0.3.tar.gz
As the above command suggests, we’ll install the application under the
/optdirectory. We’ll switch to this directory, and extract the archive:
# cd /opt # tar -xzf redmine-4.0.3.tar.gz
Optionally we can also create a
symlinkfor easier access – this way we don’t need to remember the exact version:
# ln -s /opt/redmine-4.0.3 /opt/redmine
Now we can set the
redmineuser as the owner of the extracted directory hierarchy, recursively:
# chown -R redmine:redmine /opt/redmine*
- To setup the database for the application’s connection, we have to start it up if it isn’t running already:
# systemctl start postgresql
- We’ll need to create an empty database where the application will store it’s data. To do so, we’ll switch to the
postgresoperating system user created by default at database installation:
# su - postgres
We’ll login to
psqlas the superuser of the database:
$ psql psql (10.5) Type "help" for help. postgres=#
We’ll create a role that will be used by the application (note down the username and password):
postgres=# CREATE ROLE redmine LOGIN ENCRYPTED PASSWORD 'R3DM1N3' NOINHERIT VALID UNTIL 'infinity';
We also create a new database with the owner created above:
postgres=# CREATE DATABASE rmdb WITH ENCODING='UTF8' OWNER=redmine;
We’ll need the username, password, encoding and database name in a later step.
- Now that the user is set up, we need to allow login for it on the database server. The redmine user will connect locally, so we add the following line to the
pg_hba.conffile, located by default at
/var/lib/pgsql/databy default on RHEL based distributions:
host rmdb redmine 127.0.0.1/32 md5
Check your configuration file for the following:
# IPv4 local connections: host all all 127.0.0.1/32 ident
If you have such line, comment it out, it will conflict with the login we plan to set up.
- With that in place, we need to restart the database for the settings to take effect:
# systemctl restart postgresql
- Now we have all information needed to tell the application where and how will it find the database. There is an example of the database connection configuration file with all supported databases in the
configsubdirectory of the extracted archive. We can make a copy of this file (using the
$ cp config/database.yml.example config/database.yml
We can delete or comment out all example settings besides the ones related to PostgreSQL, or just create an empty file with the needed configuration (less junk will remain in the file that way). At the end, the
/opt/redmine/config/database.ymlshould contain the following:
# PostgreSQL configuration production: adapter: postgresql database: rmdb host: 127.0.0.1 username: redmine password: "R3DM1N3"
Note that we used the database connection information we set up in the last two steps.
- To lower the number of possible problems, we’ll test that we can log in to the
rmdbdatabase with the credentials provided in the configuration file. It is easier to debug connection problems with PostgreSQL toolset than any other:
$ psql -d rmdb -U redmine -W Password for user redmine: psql (10.5) Type "help" for help. rmdb=>
- This is where the easy part ends. Now we’ll install various Ruby packages Redmine depends on. Some of them need
rootaccess, some will install in the name of the
redmineuser, and later some will probably need a repair. No kidding. First of all, we’ll need
# gem install bundler Fetching: bundler-2.0.1.gem (100%) Successfully installed bundler-2.0.1 1 gem installed
redmineuser, but we’ll also need
rootto install or repair
Ruby gems, so I suggest to open another terminal, switch to
redmineuser, and navigate to the
/opt/redminedirectory, while also keeping the root console open.
redmineuser, we start the installation in the
$ bundle install --without development test rmagick
Many dependencies will be installed, and for some the installer asks for the
sudopassword – which is the password of the
redmineuser. It seems that this sudo functionality is somehow broken a bit, and can handle some of the root privileged package installs, and can’t get on with others. The ones that fail can be installed on the root console, and the above
bundlecommand can be executed on the redmine user’s console again. What was needed to be installed in my case with
rootare the following:
# gem install nokogiri -v '1.10.2' --source 'https://rubygems.org/' # gem install pg -v '1.1.4' --source 'https://rubygems.org/'
There are also some packages that may broke during install. These can be repaired on the root console also. As with the above failed package installation steps, the output of the
bundlercommand will tell which package got problems, and how to solve it. In my case the following packages needed repair:
# gem pristine nio4r --version 2.3.1 # gem pristine redcarpet --version 3.4.0 # gem pristine websocket-driver --version 0.7.0
Please note that if you are installing another version of Redmine, the version numbers of the packages will likely differ. After fixing all broken and missing packages, the
bundlecommand should complete without errors, with the following end of the output:
[...] Installing roadie-rails 1.3.0 Fetching rouge 3.3.0 Installing rouge 3.3.0 Bundle complete! 26 Gemfile dependencies, 57 gems now installed. Gems in the groups development, test and rmagick were not installed. Use `bundle info [gemname]` to see where a bundled gem is installed.
- With the tricky part done, we need to generate a token that will be used to encode session cookies:
$ bundle exec rake generate_secret_token
- Next we generate the database objects needed by the application:
$ RAILS_ENV=production bundle exec rake db:migrate
Apart from creating the needed database objects, this step will generate a lot of output by logging all steps to the console. We’ll see a lot of entries appear similar to the following:
[...] == 20180913072918 AddVerifyPeerToAuthSources: migrating ======================= -- change_table(:auth_sources) -> 0.0082s == 20180913072918 AddVerifyPeerToAuthSources: migrated (0.0083s) ============== == 20180923082945 ChangeSqliteBooleansTo0And1: migrating ====================== == 20180923082945 ChangeSqliteBooleansTo0And1: migrated (0.0000s) =============
This process should complete in a few seconds.
- We can check the populated database with
rmdb=> \dt List of relations Schema | Name | Type | Owner --------+-------------------------------------+-------+--------- public | ar_internal_metadata | table | redmine public | attachments | table | redmine public | auth_sources | table | redmine public | boards | table | redmine public | changes | table | redmine [...]
- The last step of the installation is loading the default data into the database. By providing the
REDMINE_LANGparameter we can save ourselves from any questions during the initial loading.
$ RAILS_ENV=production REDMINE_LANG=en bundle exec rake redmine:load_default_data Default configuration data loaded.
- The installation is complete. We can start up the application:
$ bundle exec rails server webrick -e production => Booting WEBrick => Rails 18.104.22.168 application starting in production on http://0.0.0.0:3000 => Run `rails server -h` for more startup options [2019-04-14 18:39:12] INFO WEBrick 1.4.2 [2019-04-14 18:39:12] INFO ruby 2.5.1 (2018-03-29) [x86_64-linux] [2019-04-14 18:39:12] INFO WEBrick::HTTPServer#start: pid=30062 port=3000
- The application is now running and can be accessed with a browser. From the above output we can guess that it is accessible on port
3000, so if we have a firewall running on the target machine, we need to open this port to access the service remotely:
# firewall-cmd --zone=public --add-port=3000/tcp --permanent # firewall-cmd --reload
- By opening a browser and pointing it to the machine’s address and port 3000 (http://192.168.1.14:3000 on the below screenshot), we can access the web-based interface of our fresh new Redmine installation.
The default credentials are
adminfor username, and also for password. On first login the well-behaving application will prompt for a password change for this privileged account. From there the service is ours to populate, configure, and enjoy.
- With the installation complete, we can remove the
redmineuser from the
wheelgroup, eliminating the security hole needed during the process:
# gpasswd -d redmine wheel Removing user redmine from group wheel # id redmine uid=1008(redmine) gid=1008(redmine) groups=1008(redmine)