Today there is a lot of choice between project management tools for development. I have tried JIRA, Asana, ClickUp and a few others. Somehow I always return back to the essence where it all started for me years ago: Redmine.
Redmine is a web-based project management tool with a long history, stability and still is a rock solid choice and has endless extending possibilities. (in fact: it's forked and used as a base for many other project management tools).
I host a virtual server that runs openSUSE Leap 15.3. Despite counting thousands of packages in their repositories: Redmine is not included, but fortunately all the requirements for Redmine are present.
This guide will focus on recent versions of openSUSE. In case you run a Debian-based distribution (ex. Ubuntu Linux): there is a comprehensive installation guide for Redmine on their official website.
Installation on openSUSE Leap 15.3
This is what we will setup (in a nutshell):
- We install a clean version of Redmine from GitHub
- We hook it up to a MySQL based database server (MariaDB is a splendid choice)
- We use Passenger as app server (since Redmine is an application, not a website so it can not directly communicate with Apache)
- We use Apache2 as a web server and Acme.sh to get SSL certificates and enforce a solid https connection.
Get the system dependencies
Apache and MariaDB
Apache and MariaDB are easily installable through the original repositories. You can follow the well-explained steps at the original installation guide to install:
Ruby libraries and Passenger
Redmine is written in Ruby so we need to install all the necessary stuff to get a Ruby application and app server working in openSUSE:
sudo zypper in ruby2.5 ruby2.5-devel ruby2.5-rubygem-bundler rubygem-passenger rubygem-passenger-apache2 yast2-ruby-bindings
Install the latest version of Redmine
Redmine maintains an official mirror of their repository on GitHub. To get the latest version, you can do a
git clone in a directory where you would like to host the application like this (replace /srv/www/vhosts if you like to keep your sites on a different location):
mkdir /srv/www/vhosts cd /srv/www/vhosts git clone https://github.com/redmine/redmine.git
Once git has finished cloning the repository, enter the newly created redmine directory and checkout the latest stable version.
At the time of writing this article, the most stable version was 4.2.3. Verify if a more recent version is available on the Redmine GitHub page.
cd redmine/ git checkout 4.2.3
You should now get confirmation that git HEAD is at the desired version:
HEAD is now at 9f7103277 tagged version 4.2.3
Prepare the database
Assuming you have setup MariaDB correctly (if not, go back 2 chapters ⤴️!), add a new user and database for redmine and grant permissions.
Login as root user (or a different user with grant permissions)
sudo mysql -u root
Once you are at the mysql command line interface (cli), create a new database for your Redmine instance.
CREATE DATABASE redmine;
Next, create a user, obviously replace
replace_with_secure_password with a... secure password of your choice 👌!
CREATE USER 'redmine'@'localhost' IDENTIFIED BY 'replace_with_secure_password';
Finally, add permissions for the new redmine user to manage the redmine database:
GRANT ALL PRIVILEGES ON redmine.* TO 'redmine'@'localhost';
Finally flush the privileges so we can start using the new redmine user and exit the mysql cli.
FLUSH PRIVILEGES; EXIT;
Prepare the Redmine application
Create the configuration file
Now it's time to tell Redmine where it can find the right database and connect to it. In the config folder are some usefull example files. We'll follow the official installation guidelines and copy the example file as a starting point.
cp config/database.yml.example config/database.yml
Open the file with your text editor (
vim for experts,
nano for starters!) and change the production settings to your database values:
production: adapter: mysql2 database: redmine host: localhost username: redmine password: "the_secure_password_you_chose"
Note that I am assuming you've sticked to a MariaDB database as described above. mysql2 is the driver Redmine will be using to connect. If you used a different database setup, be sure to check the Redmine documentation for other options.
Install the Redmine dependencies
Since Redmine is written in Ruby, it uses some specific dependencies: we will use bundler to install these in 1 line. Note that we have installed bundler during the preparation of openSUSE above.
We exclude all development and test files since we won't be using them.
bundle install --without development test
I hope you succeeded! Now run the following script, it will generate a token that will be used for cookie storage.
bundle exec rake generate_secret_token
Fill the database with the initial structure
Redmine will need an initial setup of database tables to function correctly. Run these 2 scripts to build the tables. (it will also verify that you have done the Redmine configuration correctly!)
RAILS_ENV=production bundle exec rake db:migrate RAILS_ENV=production bundle exec rake redmine:load_default_data
With the second command (load_default_data), the script will ask for a default language. Make your choice with the given options. If you want English, you can skip this question by just hitting enter. Once finished you should get the notification that the data was successfully loaded:
==================================== Default configuration data loaded.
Set the permissions for the file system
Redmine needs a storage location for file and cache storage, create these folders and set the permissions accordingly so that our Passenger server can access them later on.
Note that I am assuming that you want to run the application as the default http user in openSUSE, which is
wwwrun. Change to your own wishes if you have or want a different configuration.
mkdir -p tmp tmp/pdf public/plugin_assets sudo chown -R wwwrun:www files log tmp public/plugin_assets sudo chmod -R 755 files log tmp public/plugin_assets
Setup apache with passenger
Passenger is an application server that will 'steer' Redmine to the webbrowser in a safe and efficient way. We will not use Passenger directly as an http endpoint. We will use Apache for this.
Main reason I prefer this type of configuration is port management: If you already have different website running (or applications like phpMyAdmin for example), you are probably already using port 80 and 443!
Activate Passenger as a module in Apache
We already installed Passenger and the module for Apache during the openSUSE setup. So you can simply enable the module:
sudo a2enmod passenger
This will allow Apache to interpret the Passenger terms inside an Apache configuration file and execute the correct applicatie when the user request the website (or better: 'application')
Add a vhost file
I hope you have thought of a (sub)domain by now where you would like to host your Redmine installation? To keep the vhost.d folder clean, I like to rename each vhost file to the domain of the site itself. **It doesn't really matter how you call the file, just don't forget the .conf extension.
Now edit the file (with your favorite text editor! 📄) and add the following configuration. Be sure to replace the domain name and email!
<VirtualHost *:443> ServerName redmine.domain_name.com ServerAdmin email@example.com DocumentRoot /srv/www/vhosts/redmine/public PassengerAppRoot /srv/www/vhosts/redmine PassengerDebugLogFile /srv/www/vhosts/redmine/error.log <Directory /srv/www/vhosts/redmine> AllowOverride All Require all granted </Directory> </VirtualHost> <VirtualHost *:80> ServerName redmine.domain_name.com RedirectMatch permanent ^/(.*) https://redmine.domain_name.com/$1 </VirtualHost>
Notice the bottom configuration
<VirtualHost *:80>, we will forward all unsafe requests on port 80 (http) automatically to https (port 443) for safety reasons.
You could theoretically test your installation by now if you reload your Apache webserver but we have not yet configured a SSL certificate for https connections.
Before proceeding to the next step: make sure your the DNS settings of your domain name (the one you defined in the vhost config above) are configured to point to the IP address of your openSUSE installation.
Get a https certificate with acme.sh
Unless you are running your Redmine installation on a local intranet or don't care about an SSL connection to your site (you should!) you can configure your certificate by now.
If you don't have strategy or setup for this: I recommend reading my 5 minute guide on how to setup SSL certificates on Apache2 with acme.sh.
Verify the installation
I hope you have made it this far! If you followed all the steps correctly and visit the domain that you pointed to your Redmine installation, you should be the following screen:
Login to Redmine
Change the admin user
Very important: By default the admin is activated with password 'admin'. Change this password immediately after your installation is up and running.
Click 'Sign in' in the header (top right corner) and login with the following credentials:
- Login: admin
- Password: admin
Now change the admin password to something more secure (Redmine requires minimum 8 characters).
After you've done this, you're good to go! In case you come across errors at this point, be sure to check the permissions of the redmine folder so that Apache can access them.
Where to go from here?
Congratulations 🎉! you have Redmine stable and running. If suggest you explore the features of your brand new installation (with the aid of the Redmine documentation)
Once you master the basics: learn how to unleash the full power and extend/customize Redmine to your needs.