Installing Redmine on Ubuntu 22.04

28/10/2025

0 Views 0

SaveSavedRemoved 0

How to Install Redmine on Ubuntu 22.04: A Complete Guide

Redmine is a powerful and flexible open-source project management and issue-tracking tool. Written using the Ruby on Rails framework, it allows teams to manage multiple projects, track bugs, handle feature requests, and collaborate effectively. Its cross-platform and cross-database support make it a go-to choice for developers, project managers, and businesses of all sizes.

This comprehensive guide will walk you through the entire process of installing Redmine on a clean Ubuntu 22.04 server, using Apache as the web server and MariaDB as the database.

Prerequisites

Before we begin, ensure you have the following:

An Ubuntu 22.04 server.
A non-root user with sudo privileges.
A domain name pointed to your server’s IP address (optional but recommended for production).

Step 1: Update Your System and Install Dependencies

First, it’s essential to update your system’s package list and install the core dependencies needed to run Redmine. This includes the Apache web server, the MariaDB database server, and other necessary libraries.

Open your terminal and run the following commands:

sudo apt update
sudo apt upgrade -y
sudo apt install -y apache2 mariadb-server mariadb-client build-essential libssl-dev libmariadb-dev ruby-dev imagemagick libmagickwand-dev

This single command accomplishes several key tasks:

Updates your package index.
Installs Apache2, our web server.
Installs MariaDB, a robust and reliable database server.
Installs Ruby and its development tools, which are required to run Redmine.
Installs ImageMagick for handling image attachments within Redmine.

Step 2: Configure the MariaDB Database

Redmine needs a dedicated database to store all its data, including projects, issues, and users. Creating a separate database and user is a critical security best practice.

Secure your MariaDB installation:
Run the included security script to set a root password, remove anonymous users, and enhance security.
```
sudo mysql_secure_installation
```
Follow the on-screen prompts. It’s highly recommended to set a strong root password and answer ‘Y’ to all subsequent questions.
Create the Redmine Database and User:
Log in to the MariaDB shell as the root user.
```
sudo mysql -u root -p
```
Now, execute the following SQL commands to create the database, a new user, and grant the necessary permissions. Replace your_strong_password with a secure password of your own.
```
CREATE DATABASE redminedb CHARACTER SET utf8mb4;
CREATE USER 'redmineuser'@'localhost' IDENTIFIED BY 'your_strong_password';
GRANT ALL PRIVILEGES ON redminedb.* TO 'redmineuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```
Make a note of the database name, username, and password, as you will need them shortly.

Step 3: Install Ruby and Bundler

While we installed some Ruby components earlier, we need to ensure we have the right versions and the Bundler gem for managing application dependencies.

sudo apt install -y ruby ruby-bundler

Verify the installation by checking the versions:

ruby -v
gem -v

Step 4: Download and Configure Redmine

Now it’s time to download the latest stable version of Redmine and configure it to connect to our database.

Download and Extract Redmine:
Navigate to the /opt directory, which is a common location for installing optional software. Check the official Redmine website for the latest version number and update the command if necessary.
```
cd /opt
sudo wget https://www.redmine.org/releases/redmine-5.1.2.tar.gz
sudo tar -xvzf redmine-5.1.2.tar.gz
sudo mv redmine-5.1.2 /opt/redmine
```
Configure the Database Connection:
Navigate to the Redmine config directory and create a copy of the example database configuration file.
```
cd /opt/redmine/config
sudo cp database.yml.example database.yml
```
Now, open the new database.yml file with a text editor like nano.
```
sudo nano database.yml
```
Find the production: section and modify it with the database credentials you created in Step 2. It should look like this:
```
production:
  adapter: mysql2
  database: redminedb
  host: localhost
  username: redmineuser
  password: "your_strong_password"
  encoding: utf8mb4
```
Save and close the file (Ctrl+X, then Y, then Enter in nano).
Install Redmine Dependencies and Prepare the Database:
Navigate back to the main Redmine directory.
```
cd /opt/redmine
```
Install all the required Ruby gems using Bundler. We exclude the development and test groups to keep the installation lean for production.
```
sudo bundle config set --local without 'development test'
sudo bundle install
```
Next, generate a secret key for session security and run the database migrations to create the necessary tables.
```
sudo bundle exec rake generate_secret_token
sudo RAILS_ENV=production bundle exec rake db:migrate
```
Load Default Data (Optional):
For a new installation, it’s helpful to load the default data, which includes basic trackers, roles, and settings.
```
sudo RAILS_ENV=production bundle exec rake redmine:load_default_data
```
When prompted, select your preferred language (e.g., en for English).

Step 5: Set File Permissions and Install Passenger

For Apache to serve Redmine correctly and for Redmine to function properly, we must set the correct file permissions and install Phusion Passenger, an application server that bridges Apache and the Ruby on Rails application.

Set Permissions:
Change the ownership of the Redmine directory to the Apache user (www-data).
```
sudo chown -R www-data:www-data /opt/redmine
sudo chmod -R 755 /opt/redmine
```
Install Phusion Passenger:
Passenger simplifies deploying Ruby applications. Install it directly from the Ubuntu repositories.
```
sudo apt install -y libapache2-mod-passenger
```
Enable the necessary Apache modules.
```
sudo a2enmod passenger rewrite
sudo systemctl restart apache2
```

Step 6: Configure Apache to Serve Redmine

The final step is to create an Apache Virtual Host file that tells the server how to handle requests for your Redmine site.

Create the Virtual Host File:

sudo nano /etc/apache2/sites-available/redmine.conf

Add the Configuration:
Paste the following configuration into the file. If you are using a domain, replace your_domain.com with your actual domain name. If you are just using an IP, you can remove the ServerName line.

<VirtualHost *:80>
    ServerName your_domain.com
    ServerAdmin admin@your_domain.comDocumentRoot /opt/redmine/public
RailsEnv production

&lt;Directory /opt/redmine/public&gt;
    Allow from all
    Options -MultiViews
    Require all granted
&lt;/Directory&gt;

ErrorLog ${APACHE_LOG_DIR}/redmine_error.log
CustomLog ${APACHE_LOG_DIR}/redmine_access.log combined
</VirtualHost>

This configuration tells Apache that the root directory for this site is Redmine’s public folder and to run it in the production environment.

Enable the Site and Restart Apache:
Disable the default Apache site, enable your new Redmine site, and restart Apache for the changes to take effect.
```
sudo a2dissite 000-default.conf
sudo a2ensite redmine.conf
sudo systemctl restart apache2
```

Step 7: Access and Secure Your Redmine Installation

You should now be able to access your new Redmine instance by navigating to your server’s IP address or domain name in your web browser.

Default Login:
- Username: admin
- Password: admin

Your first and most important action is to change the default administrator password. Log in, click “Administration” in the top menu, select “Users,” click on the “admin” user, and then click the “Change password” link.

For a production environment, you should also:

Configure a firewall: Use UFW (Uncomplicated Firewall) to allow traffic only on necessary ports (SSH, HTTP, HTTPS). sudo ufw allow 'Apache Full'
Set up SSL/TLS: Use Certbot and Let’s Encrypt to secure your site with free HTTPS, protecting user data and improving trust.

Congratulations! You have successfully installed a powerful, self-hosted project management system on your Ubuntu 22.04 server.

Source: https://kifarunix.com/install-redmine-on-ubuntu-22-04/