Install and Setup Redmine on Ubuntu VPS with Subdomain


Redmine is a flexible and powerful open-source project management system written in Ruby on Rails. Hence, startup usually use features for managing multiple projects, tracking issues and bugs, handling documents and files, time tracking, and more.

In this article, we will go over the steps to set up Redmine on a VPS running Ubuntu. We will also use a proxy to pass the Rails server to the subdomain, allowing you to access the Redmine website in your browser.

The following topics will be covered:

  • Setup Ruby/Rails on Linux
  • Setup Database Management System
  • Install Redmine On Ubuntu 
  • Configuring Redmine to Run as a Service
  • Subdomain Load Redmine Server via Proxy Pass

I. Setup Ruby/Rails on Linux

First and foremost, we will need to install the dependencies required for Ruby and Rails and without Ruby and Rails, Redmine would not be able to function properly.

sudo apt install curl zlib1g-dev build-essential libssl-dev libyaml-dev sqlite3 libxml2-dev libxslt1-dev libcurl4-openssl-dev software-properties-common libffi-dev 

You can use the dpkg command to check if the packages are installed on your Ubuntu system. 

dpkg -s curl zlib1g-dev

After installing the required dependencies, checking the version of Ruby and Rails can be done by running the following commands:

ruby -v
ruby 2.7.0p0 (2019-12-25 revision 647ee6f091) [x86_64-linux-gnu]
rails -v

Gemfile, and Gemfile.lock are important components of the Ruby on Rails ecosystem. The Gemfile is a file in a Ruby on Rails application that lists the gems required by the application. The Gemfile.lock file is automatically generated by Bundler, which is the package manager used by Ruby on Rails.

sudo gem update
sudo gem install bundler

Would you like to visualize how to use gem? Let us visit the Redmine source code here and observe the Gemfile.

    gem 'rails', ''
	gem 'rouge', '~> 4.1.0'
	gem 'request_store', '~> 1.5.0'
	gem 'mini_mime', '~> 1.1.0'
	gem "actionpack-xml_parser"
	gem 'roadie-rails', '~> 3.0.0'
	gem 'marcel'
	gem 'mail', '~> 2.8.1'
	gem 'nokogiri', '~> 1.14.0'
	gem 'i18n', '~> 1.13.0'
	gem 'rbpdf', '~> 1.21.1'
	gem 'addressable'
	gem 'rubyzip', '~> 2.3.0'

Sometimes, you may be missing the mysql2 dependency in your Gemfile. In this case, you will need to install mysql2 by running the following command:

sudo gem install mysql2

To add the mysql2 gem to your Gemfile, open the file in a text editor and add the following line:

    gem 'rails', ''
	gem 'rouge', '~> 4.1.0'
	gem 'request_store', '~> 1.5.0'
	gem 'mini_mime', '~> 1.1.0'
	gem "actionpack-xml_parser"
	gem 'roadie-rails', '~> 3.0.0'
	gem 'marcel'
    gem "mysql2"
	gem 'mail', '~> 2.8.1'
	gem 'nokogiri', '~> 1.14.0'
	gem 'i18n', '~> 1.13.0'
	gem 'rbpdf', '~> 1.21.1'
	gem 'addressable'
	gem 'rubyzip', '~> 2.3.0'

Note: Using sudo nano Gemfile to open text editor.

In Ruby/Rails application, bundle install is used to install all the necessary gems (Ruby libraries) specified in the Gemfile of the application. The Gemfile lists all the required gems and their versions that are needed for the application to run.

bundle install && bundle update

Running bundle install is an important step when setting up a new Ruby/Rails application or when deploying an application to a new environment.

II. Setup Database Management System

MariaDB is a community-driven fork of the popular MySQL database management system, and is a widely used, free and open-source relational database management system. Hence, let us install the MariaDB database management system on a Linux-based operating system.

sudo apt install mariadb-server

Use the following command to check if the package has been installed successfully or not.

sudo systemctl status mariadb || sudo mysql --version

The next step, create a new MySQL/MariaDB database named admin_redmine, new MySQL/MariaDB user named adminRedmine with the password Abc@123456, and grant all privileges on the admin_redmine database to this user.

sudo mysql -u root -p
mysql> CREATE DATABASE admin_redmine CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
mysql> CREATE USER 'adminRedmine'@'localhost' IDENTIFIED BY 'Abc@123456';
mysql> GRANT ALL PRIVILEGES ON admin_redmine.* TO 'adminRedmine'@'localhost';
mysql> EXIT;

Open terminal and type the following command to log in to the MySQL server as the `adminRedmine` user and enter password in prompt.

mysql -u adminRedmine -p

We methods can be used to start the Redmine server:

  • Web Servers - using libapache2-mod-passenger Apache module.
  • Application Servers - using sudo bundle exec rails server -e production command.

Here, we will focus on using Application Servers to launch the Redmine server. This is because we need to attach the subdomain, which has been created and managed by the Plesk panel. It can be challenging to install the libapache2-mod-passenger Apache module on Plesk for Linux, which uses the Apache HTTP Server.

III. Install Redmine On Ubuntu

To obtain the various releases of the Redmine project management software, we need to visit the link Installing a version that is greater than 5.0.0 will help avoid errors from previous versions, so we should prioritize installing a version that is newer than 5.0.0.

tar xzf redmine-5.0.5.tar.gz
sudo cp -r redmine-5.0.5 redmine
sudo rm -rf redmine-5.0.5
sudo rm -rf redmine-5.0.5.tar.gz

In some cases, it can be assumed that Redmine has already been installed on your local or VPS. In such cases, you can check the current version of Redmine using the following command:

cat lib/redmine/version.rb

Use the ls -l command to list the owner and group of the directory:

ls -l /var/www/vhosts/

Note: When you run the command, it will display a list of files and directories in the specified directory along with their respective owner and group.

Moving forward, check the permissions of the Redmine directory and ensure that the Apache user has permission to access it. You can do this by running the following command:

sudo chown -R <username>:<usergroup> /var/www/vhosts/

Before running bundle install --without development test, it's important to configure the database.yml file in Redmine because this file contains the necessary information for Redmine to connect to the database.

sudo cp -r config/database.yml.example config/database.yml
sudo nano database.yml

» database.yml

  adapter: mysql2
  database: admin_redmine
  host: localhost
  username: adminRedmine
  password: Abc@123456
  # Use "utf8" instead of "utfmb4" for MySQL prior to 5.7.7
  encoding: utf8mb4

  adapter: mysql2
  database: admin_redmine
  host: localhost
  username: adminRedmine
  password: Abc@123456
  # Use "utf8" instead of "utfmb4" for MySQL prior to 5.7.7
  encoding: utf8mb4

# Warning: The database defined as "test" will be erased and
# re-generated from your development database when you run "rake".
# Do not set this db to the same as development or production.
  adapter: mysql2
  database: admin_redmine
  host: localhost
  username: adminRedmine
  password: Abc@123456

Install the required gems using bundler:

bundle install --without development test

Note: In certain cases, we may need to use 'sudo gem <package>' to install essential packages if they are not already installed.

To generate a new secret token in a Rails application, you can run the following command in the terminal:

sudo bundle exec rake generate_secret_token || bundle exec rake generate_secret_token

In the context of a Rails application like Redmine,we need typically perform using a migration tool like rake db:migrate.

sudo bundle exec rake db:migrate

If you want to apply database changes to a production server.

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

Loading default data is usually done after initializing the database schema and before starting to use Redmine, to ensure that the system has all the necessary data for its proper functioning.

sudo bundle exec rake redmine:load_default_data

Running a Rails application server in production mode ensures that the application is optimized for a live production environment, with appropriate settings and security measures in place.

sudo chmod -R 0777 .bundle/ 
sudo chmod -R 0777 Gemfile.lock 
bundle exec rails server -e production or sudo bundle exec rails server -e production

Rails application server in production mode listens on port 3000. If port 3000 is already in use by another process or application, you can use the sudo lsof -i :3000 command to find the Process ID (PID) of the process that is using that port. Once you have the PID, you can use the sudo kill <pid> command to stop that process and free up the port for use by the Rails application server.

sudo lsof -i :3000
sudo kill <pid>

Using common curl command used for check whether the Redmine server is running means sending an HTTP request.

curl -I
curl --verbose

IV. Configuring Redmine to Run as a Service

First and foremost, let list all files, including hidden files, in the current directory /etc/systemd/system, you can use the command:

/etc/systemd/system$ ls -a
 ..                                      'snap-amazon\x2dssm\x2dagent-4046.mount'
 bind9.service                           'snap-amazon\x2dssm\x2dagent-6312.mount'
 cloud-final.service.wants                snap-core18-2714.mount                  snap-core18-2721.mount
 dbus-org.freedesktop.resolve1.service    snap-core20-1828.mount
 dbus-org.freedesktop.timesync1.service   snap-core20-1852.mount                     snap-lxd-21835.mount
 elasticsearch.service                    snap-lxd-24061.mount                   snap-snapd-18596.mount                       snap-snapd-18933.mount                                snap.lxd.activate.service
 iscsi.service                            snap.lxd.daemon.service
 mdmonitor.service.wants                  snap.lxd.daemon.unix.socket        
 mysql.service                            [email protected]
 mysqld.service                           sshd.service    
 open-vm-tools.service.requires           syslog.service             
 plesk-ssh-terminal.service.d             vmtoolsd.service

» redmine.service

Description=Redmine Rails Server
ExecStart=/bin/bash -lc 'sudo bundle exec rails server -e production'


• Reload the systemd daemon to load the new service and enable the service to start at boot time:

sudo systemctl daemon-reload
sudo systemctl enable redmine.service
sudo systemctl start redmine.service

V. Subdomain Load Redmine Server via Proxy Pass

First and foremost, enable certain modules required for proxying requests to another server from Apache server. Hence, you need to configure your web server to proxy the requests to the Rails server.

sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod proxy_balancer
sudo a2enmod lbmethod_byrequests

In Plesk panel, the Apache configuration for a domain is managed through the Plesk interface and is stored in a different location than the default Apache configuration files located in /etc/apache2/sites-available.

Let move to open file /var/www/vhosts/system/ and modify two properties:

DocumentRoot "/var/www/vhosts/"
<Directory /var/www/vhosts/> ... </Directory>

Running sudo systemctl restart apache2 restarts the Apache web server, which is necessary to apply any new configurations that have been made.

curl --verbose
curl --verbose

Note: Remove ErrorDocument directive in the Apache httpd.conf file that is used to customize the error pages that are displayed when a specific HTTP error occurs.

To test the functionality of Redmine pages would require you to access the Redmine server through the proxy pass configured to use port 80, rather than directly accessing the server on port 3000.

» /var/www/vhosts/system/

<IfModule mod_ssl.c>

	<VirtualHost >
		ServerName ""
		ServerAlias ""
		ServerAlias ""
		UseCanonicalName Off
                ProxyPreserveHost On
                ProxyPass / http://localhost:3000/
                ProxyPassReverse / http://localhost:3000/
		CustomLog /var/www/vhosts/system/ 
		ErrorLog "/var/www/vhosts/system/"

Finally, run sudo systemctl restart apache2 to restart the Apache server. After the server has restarted, you should be able to access Redmine through the subdomain configured in the previous steps. Verify that the configuration is working correctly by visiting the subdomain in your web browser. If the configuration is set up correctly, you should be able to access Redmine through the subdomain without any issues.

VI. Conclusion

In the article, Installing and setting up Redmine on an Ubuntu VPS with a subdomain can provide a powerful project management tool for development teams. By following the necessary steps to install and configure Redmine, as well as configuring Apache to use a subdomain, developers can easily access Redmine from a dedicated URL. Additionally, Redmine's flexible and customizable features, such as issue tracking, time tracking, and project wikis, make it a popular choice for managing projects and collaborating with team members. With proper maintenance and updates, Redmine can help streamline project workflows and improve team productivity.

Vuong Nguyen
Vuong Nguyen The individual is sociable and enjoys making friends, often sharing knowledge across various fields. |1 second ago
Vuong Nguyen The individual is sociable and enjoys making friends, often sharing knowledge across various fields. 1 second ago
You need to login to do this manipulation!