Install Redmine on openSUSE Leap 15.3
A guide on how to get Redmine installed in the year 2022
Table of contents
About Redmine
Today there are a lot of choices between project management tools for development. I have tried JIRA, Asana, ClickUp and a few others. Somehow I always return to the essence of where it all started for me years ago: Redmine.
Redmine is a web-based project management tool with a long history, stability and still 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
Setup layout
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 an 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 in 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 its 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 in 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 check out 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 set up 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';
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 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 useful 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 stuck 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 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 web browser in a safe and efficient way. We will not use Passenger directly as an HTTP endpoint. We will use Apache for this.
The main reason I prefer this type of configuration is port management: If you already have a different website running (or applications like phpMyAdmin for example), you are probably already using ports 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 application when the user requests the website (or better: 'application')
Add a virtual host 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 virtual host file to the domain of the site itself. **It doesn't matter how you call the file, just don't forget the .conf extension.
touch /etc/apache2/vhosts.d/redmine.domain.conf
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 your@email.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 http (port 80) 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 an SSL certificate for https connections.
Before proceeding to the next step: make sure the DNS settings of your domain name (the one you defined in the virtual host 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 set up 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 for your Redmine installation, you should see the following screen:
Login to Redmine
Change the admin user
Very important: By default, the admin is activated with the password 'admin'. Change this password immediately after your installation is up and running.
Click 'Sign in' in the header (top right corner) and log in with the following credentials:
Login: admin
Password: admin
Now change the admin password to something more secure (Redmine requires minimum of 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. I 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.
Have fun!