Redmine is a free and open-source project management software and bug-tracking tool. It is a self-hosted project management tool written in Ruby and the Ruby on Rails framework. Redmine can be integrated with various VCS (Version Control Systems) such as Git, Mercurial, etc. It offers a repository manager, a browser, and a diff viewer. Redmine can manage projects with wikis and forums, time tracking, and role-based access control. It is cross-platform, can be installed anywhere, and supports multiple RDBMS and up to 49 languages.
In this guide, you will install Redmine, the project management and issue-tracking tool, on a Debian 11 server. In this guide, the Apache2 web server is used as a reverse proxy for Redmine, and the MariaDB database server is used as the default database. You will have a production-ready Redmine installation secured with SSL certificates.
Prerequisites
To get started with this tutorial, you will need the following prerequisites:
- A Debian 11 server - this demo uses the Debian server with the hostname "redmine-server".
- A non-root user with root/administrator privileges.
- A domain name pointing to the IP address of the Debian server.
Now, let's start the Redmine installation.
Installing the dependencies
In the first step, you will install some package dependencies for Redmine on your Debian server. Redmine is a web application written in Ruby. Therefore, you will install dependencies that include Ruby on your system.
Run the following apt command to update and refresh the Debian package index.
sudo apt update
Install the dependencies for Redmine using the following apt command. When prompted to confirm the installation, type y and press ENTER to continue.
sudo apt install build-essential ruby ruby-dev libxslt1-dev libxml2-dev zlib1g-dev imagemagick libmagickwand-dev curl vim
After the package dependencies are installed, proceed to the next step to install the Apache2 web server and the MariaDB database server.
Installing the Apache2 web server
Redmine can be operated with Apache2 and Nginx. In this example, you will use the Apache2 web server as a reverse proxy for your Redmine installation.
Run the following apt command to install Apache2 packages. This command will also install the "libapache2-mod-passenger" package, which will allow you to run the Ruby web application on Apache2.
When prompted to confirm the installation, type Y and press ENTER to continue.
sudo apt install apache2 apache2-dev libapache2-mod-passenger
Once Apache2 is installed, check the "apache2" service with the following systemctl command to make sure it is enabled and running.
sudo systemctl is-enabled apache2 sudo systemctl status apache2
You should see that the "apache2" service is enabled and running automatically on system startup. And the current status of the "apache2" service is "running".
Installation of MariaDB Server
After you have installed the Apache2 web server, you now install the MariaDB database server on your Debian system. The Redmine web application supports several RDMBS, including PostgreSQL and MySQL/MariaDB.
In this step you install MariaDB and set up the deployment with the script"mysql_secure_installation".
Install the MariaDB database server with the apt command below. Enter Y to confirm the installation and press ENTER to continue.
sudo apt install mariadb mariadb-server libmariadb-dev
After MariaDB is installed, run the following command to check the MariaDB service and make sure the service is running.
sudo systemctl is-enabled mariadb sudo systemctl status mariadb
You will see that the MariaDB service is enabled, i.e. it will run automatically at system startup. And the status of the current MariaDB service is running.
Next, you need to secure the MariaDB installation with the "mysql_secure_installation" script. This includes setting up the MariaDB root password, disabling the remote root login and removing the default database and anonymous user.
Run the "mysql_secure_installation" command to secure your MariaDB installation.
sudo mysql_secure_installation
You will be prompted for some of the following MariaDB server configurations.
- Switch to unix_socket for authentication? enter n for no.
- Set up root password? enter y, then enter your password and repeat it.
- Deactivate remote root login? enter y to confirm and deactivate the entry.
- Remove anonymous user? enter y to remove the anonymous user.
- Remove standard database test? confirm with y.
- Finally, enter to reload the permissions for the tables and apply the new changes to the MariaDB server.
Adding a Redmine user
For the installation of Redmine, it is recommended to use a non-root user or to create a separate user for the Redmine installation.
Now create a new user to be used for running Redmine.
Create a new user "redmine" with the command below. In this example, you create a new user with the default home directory "/opt/redmine" and activate the bash shell.
Also enter the password for your new user and repeat it.
sudo useradd -r -m -d /opt/redmine -s /bin/bash redmine sudo passwd redmine
Next, run the following command to add the user"www-data" to the"redmine" group. This is necessary because the Redmine web application runs under the user "redmine" and Apache2 requires access rights to the Redmine directory.
sudo usermod -aG redmine www-data
Now go to the next step to set up the database and the user for Redmine.
Create new database and user
To create a new MariaDB database and a new user, you must log into the MariaDB shell using the mysql command below.
sudo mysql -u root -p
Once you are logged in, run the following queries to create a new database and user for Redmine. In this example, you create a new database "redmine_db" with the user "redmine@localhost" and change the password.
CREATE DATABASE redmine_db; CREATE USER redmine@localhost IDENTIFIED BY 'password'; GRANT ALL ON redmine_db.* to redmine@localhost; FLUSH PRIVILEGES;
Next, run the following queries to check the user rights for "redmine@localhost". Then log out of the MariaDB shell.
SHOW GRANTS FOR redmine@localhost; quit
In the following output you will see that the user " redmine@localhost" has rights for the database "redmine_db".
If all requirements are met, you can start the installation of Redmine.
Installation of Redmine
Before you start installing Redmine, run the following gem command to install "bundler", the command line for installing Ruby dependencies.
sudo gem install bundler
Now run the following command to download the Redmine source code to the"/opt/" directory. At the time of writing this article, the latest version of Redmine is v5.0.2.
wget https://www.redmine.org/releases/redmine-5.0.2.tar.gz -P /opt
Once the Redmine source code is downloaded, you will see the file "redmine-5.0.2.tar.gz" in the directory"/opt/".
Unpack the file "redmine-5.0.2.tar.gz" with the tar command below into the directory "/opt/redmine". Also execute the following command as user "redmine".
sudo -u redmine tar xzf /opt/redmine-5.0.2.tar.gz -C /opt/redmine/ --strip-components=1
Now log in as user "redmine" with the following command. From now on you will execute commands as user"redmine" and set up the Redmine installation.
su - redmine
Execute the following command to copy some default configurations for Redmine.
- The file "database.yml" is the database configuration for Redmine. You can have multiple databases for different environments such as the development and production environments.
- The file "configuration.yml" is the main configuration for your Redmine installation. You can change the detailed configurations as needed.
- The file "dispatch.fcgi" is the CGI configuration for Redmine.
cp config/database.yml.example config/database.yml cp config/configuration.yml.example config/configuration.yml cp public/dispatch.fcgi.example public/dispatch.fcgi
Edit the database configuration "config/database.yml" with the nano editor.
nano config/database.yml
Change the database configurations for the "production environment". Change the database name, user name and password with your configurations.
production: adapter: mysql2 database: redmine_db host: localhost username: redmine password: "password" encoding: utf8
Save the file and exit the editor when you are finished.
Next, run the following commands to download and install the Ruby dependencies for Redmine.
bundle config set --local without 'development test' bundle install
You should see the download and installation process of the Ruby dependencies for Redmine.
After the dependencies are installed, run the following command to generate the secret token for Redmine and migrate the database. The secret token is automatically generated and saved in the"configuration.yml". The new database schema is created for the migration of the database.
bundle exec rake generate_secret_token RAILS_ENV=production bundle exec rake db:migrate
After the database migration is complete, load the default configuration for Redmine using the command below.
RAILS_ENV=production REDMINE_LANG=en bundle exec rake redmine:load_default_data
You should see a message like"Default configuration data loaded".
This completes the installation and configuration of the Redmine project management and issue tracking tool. To check your installation, you can start the Redmine project with the following command.
bundle exec rails server -u webrick -e production
Now the Redmine web application will run with the default TCP port 3000 via WEBrick. Below you can see the output of the command.
Open the web browser and call the IP address of your server followed by the WEBrick port 3000.
If your Redmine installation was successful, you will see the home page of your Redmine web application as below.
Finally, go back to your terminal and press"Ctrl+c" to exit the WEBrick process. Next, you will set up the Apache2 web server as a reverse proxy for Redmine.
Running Redmine with reverse proxy
In this guide, you will run Redmine with Apache2 reverse proxy and SSL enabled. So make sure you have created SSL certificates for your domain name. You can generate free SSL from Letsencrypt.
Before creating a virtual host configuration, enable some of the Apache2 modules with the a2enmod command (see below).
sudo a2enmod ssl rewrite
Now create a new file for the virtual host "/etc/apache2/sites-available/redmine.conf" with the nano editor.
sudo nano /etc/apache2/sites-available/redmine.conf
Add the following configuration to the file and make sure that you change the domain name and the path of the SSL certificates.
<VirtualHost *:80> ServerName redmine.hwdomain.io ServerAdmin [email protected] # Redirect Requests to SSL Redirect permanent "/" "https://redmine.hwdomain.io/" </VirtualHost> <IfModule mod_ssl.c> <VirtualHost *:443> ServerName redmine.hwdomain.io RailsEnv production DocumentRoot /opt/redmine/public ErrorLog ${APACHE_LOG_DIR}/redmine.hwdomain.io.error.log CustomLog ${APACHE_LOG_DIR}/redmine.hwdomain.io.access.log combined SSLEngine on SSLCertificateFile /etc/letsencrypt/live/redmine.hwdomain.io/fullchain.pem SSLCertificateKeyFile /etc/letsencrypt/live/redmine.hwdomain.io/privkey.pem <Directory "/opt/redmine/public"> Allow from all Require all granted </Directory> </VirtualHost> </IfModule>
Save the file and exit the editor when you are finished.
Next, activate the configuration of the virtual host "redmine.conf" with the command a2ensite below. Then, check the Apache2 configuration to make sure you have the correct Apache configurations.
sudo a2ensite redmine.conf sudo apacectl configtest
If you have a correct Apache2 configuration, you will see the message "Syntax OK".
Finally, run the following systemctl command to restart the Apache2 service and apply the new configuration file for the virtual host.
sudo systemctl restart apache2
Now the Apache2 reverse proxy configuration for Redmine is complete. Your Redmine is now accessible via the domain name of your installation.
Finish
Open the web browser and visit the domain name of your Redmine installation (e.g.: https://redmine.hwdomain.io/). You should see the default start page of Redmine Project Management.
Click on the"Login" button in the top right corner to log in to the Redmine administration dashboard.
Log in to the Redmine administration dashboard with the default user"admin" and password"admin".
You will now be prompted to change the default password for Redmine. Enter your new password and click on"Apply".
Now change the default account data of your Redmine administrator and then click on"Save". This completes the basic configuration for Redmine.
Click on the "Projects" menu to manage projects in your Redmine installation.
Click on the "Administration" menu to set up Redmine for your organization. You can add more users, set up groups, define roles, enable authentication via a third-party application such as LDAP and much more.
Conclusion
In this tutorial, you have installed and configured Redmine, the project management and issue tracking tool, on the Debian 11 server. You have installed Redmine with MariaDB as the default database and Apache2 as a reverse proxy. You have also secured the Redmine deployment via SSL and HTTPS connections.
To extend your Redmine installation, you may want to integrate Redmine into your existing infrastructures, e.g. by adding LDAP authentications and integrating with SCM such as SVN, Git and Mercurial. You can also add roles for your organization or company.