Operating System CentOS

How to Install Redmine 7.0 on AlmaLinux 9 or Rocky Linux 9

Set up Redmine 7.0 on AlmaLinux 9 or Rocky Linux 9, the successors of CentOS 7, using Ruby 3.3, PostgreSQL, Puma and nginx.

Redmine is a web-based project management and issue tracking application written in Ruby on Rails. This guide installs Redmine 7.0 on AlmaLinux 9 or Rocky Linux 9 (it applies equally to CentOS Stream 9 and RHEL 9) with PostgreSQL as the database, Puma as the application server and nginx in front of it. At the end you will have Redmine running as a systemd service and reachable at your own domain.

CentOS 7 reached end of life in June 2024 and its Ruby 2.0 packages cannot run any maintained Redmine release. AlmaLinux 9 and Rocky Linux 9 are the drop-in successors, and they ship a Ruby version that Redmine 7.0 supports as an AppStream module.

Requirements

  • An AlmaLinux 9 or Rocky Linux 9 server, updated to a current 9.x minor release (the Ruby 3.3 module arrived with 9.4).
  • A user with sudo rights (the examples use deploy).
  • A DNS record such as redmine.example.com pointing to the server.

The Redmine installation guide lists these supported combinations:

RedmineRubyRailsDatabases listed
7.03.2, 3.3, 3.4, 4.08.1PostgreSQL 14, MySQL 8.0–8.4, SQL Server 2012+, SQLite 3 (not for production)
6.13.2, 3.3, 3.47.2same as 7.0

The default ruby package on the RHEL 9 family is 3.0, which is too old. The ruby:3.3 module stream is the right choice. A ruby:4.0 stream also exists on recent 9.x releases, but Redmine recommends Ruby 4.0.4 or later because of a wiki rendering slowdown in earlier 4.0 builds, so 3.3 is the safer pick.

Step 1: Install Ruby, PostgreSQL and build tools

Update the system, enable the CRB repository (it provides libyaml-devel, which is needed when Bundler compiles the psych gem) and enable the module streams:

sudo dnf upgrade -y
sudo dnf install -y dnf-plugins-core
sudo dnf config-manager --set-enabled crb
sudo dnf module enable -y ruby:3.3 postgresql:16

Install the packages:

sudo dnf install -y ruby ruby-devel rubygem-bundler gcc gcc-c++ make redhat-rpm-config \
  libyaml-devel openssl-devel zlib-devel libpq-devel postgresql-server nginx tar

Check the interpreter:

ruby -v

The output must show a 3.3.x version.

Step 2: Create the database

Initialise PostgreSQL and start it:

sudo postgresql-setup --initdb
sudo systemctl enable --now postgresql

Create a system account that will own and run Redmine, then a database role with the same name and a UTF-8 database owned by it:

sudo useradd --system --create-home --shell /bin/bash redmine
sudo -u postgres psql -c "CREATE ROLE redmine LOGIN NOINHERIT;"
sudo -u postgres psql -c "CREATE DATABASE redmine WITH ENCODING='UTF8' OWNER=redmine;"

Because the Linux user and the database role share a name, PostgreSQL's default peer authentication on the local socket lets Redmine connect without a password. If your database runs on another host, create the role with a password instead (CREATE ROLE redmine LOGIN ENCRYPTED PASSWORD '...' NOINHERIT;) and add host and password to the configuration in the next step.

Step 3: Download and configure Redmine

Look up the current release on the Redmine download page; these commands use 7.0.3. Download the archive and its checksum file, and verify it:

cd /tmp
curl -LO https://www.redmine.org/releases/redmine-7.0.3.tar.gz
curl -LO https://www.redmine.org/releases/redmine-7.0.3.tar.gz.sha256
sha256sum -c redmine-7.0.3.tar.gz.sha256

Unpack it to /opt/redmine and hand it to the redmine user:

sudo mkdir /opt/redmine
sudo tar -xzf redmine-7.0.3.tar.gz -C /opt/redmine --strip-components=1
sudo chown -R redmine:redmine /opt/redmine

Write the database configuration. Create the file from scratch rather than copying database.yml.example: Redmine's Gemfile installs a database driver for every adapter named in this file, and the example also contains MySQL sections you do not need.

sudo -u redmine tee /opt/redmine/config/database.yml > /dev/null <<'EOF'
production:
  adapter: postgresql
  database: redmine
  host: /var/run/postgresql
  username: redmine
  encoding: utf8
EOF

Switch to the redmine user for the remaining application steps:

sudo -iu redmine
cd /opt/redmine

Redmine does not load an application server in production by default. Add Puma through Gemfile.local, which Bundler picks up automatically, and install the gems into the application directory:

echo "gem 'puma'" > Gemfile.local
bundle config set --local path 'vendor/bundle'
bundle config set --local without 'development test'
bundle install

Generate the session secret, create the schema and load the default roles, trackers and workflows:

bundle exec rake generate_secret_token
RAILS_ENV=production bundle exec rake db:migrate
RAILS_ENV=production REDMINE_LANG=en bundle exec rake redmine:load_default_data

Change REDMINE_LANG to another language code if you want the default data in a different language. Then leave the redmine shell:

exit

Step 4: Run Redmine as a service

Create /etc/systemd/system/redmine.service:

[Unit]
Description=Redmine (Puma)
After=network.target postgresql.service

[Service]
Type=simple
User=redmine
Group=redmine
WorkingDirectory=/opt/redmine
Environment=RAILS_ENV=production
ExecStart=/usr/bin/bundle exec puma -e production -b tcp://127.0.0.1:3000
Restart=on-failure

[Install]
WantedBy=multi-user.target

Start it and confirm that it answers locally:

sudo systemctl daemon-reload
sudo systemctl enable --now redmine
curl -I http://127.0.0.1:3000/

You should get an HTTP/1.1 200 OK response. If not, read the log with sudo journalctl -u redmine -e and /opt/redmine/log/production.log.

Step 5: Put nginx in front

Create /etc/nginx/conf.d/redmine.conf:

server {
    listen 80;
    server_name redmine.example.com;

    client_max_body_size 20m;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

SELinux blocks nginx from opening connections to a local port until you allow it. Set the boolean, open the firewall and start nginx:

sudo setsebool -P httpd_can_network_connect 1
sudo firewall-cmd --permanent --add-service=http --add-service=https
sudo firewall-cmd --reload
sudo nginx -t
sudo systemctl enable --now nginx

For HTTPS, Certbot is available from EPEL:

sudo dnf install -y epel-release
sudo dnf install -y certbot python3-certbot-nginx
sudo certbot --nginx -d redmine.example.com

Step 6: Log in and finish the setup

Open https://redmine.example.com and sign in with the default account admin / admin. Redmine asks you to change the password immediately. Then go to Administration > Settings and set the host name and protocol so that links in notification emails are correct.

Outgoing email and other server-side options live in config/configuration.yml. Copy the example, edit the email_delivery section for your SMTP server and restart the service:

sudo -u redmine cp /opt/redmine/config/configuration.yml.example /opt/redmine/config/configuration.yml
sudo -u redmine nano /opt/redmine/config/configuration.yml
sudo systemctl restart redmine

Optional features need extra software: ImageMagick for Gantt chart PNG export and image thumbnails (on the RHEL 9 family it comes from EPEL), Ghostscript for PDF thumbnails, and the git or subversion binaries for repository browsing.

Backups and upgrades

Two things hold your data: the database and the files directory with uploaded attachments. Back up both regularly:

sudo -u redmine pg_dump -Fc -f /home/redmine/redmine-$(date +%F).dump redmine
sudo tar -czf /root/redmine-files-$(date +%F).tar.gz -C /opt/redmine files

To upgrade, unpack the new release into a fresh directory, copy config/database.yml, config/configuration.yml, Gemfile.local, the files directory and any plugins across, then run bundle install, bundle exec rake generate_secret_token and RAILS_ENV=production bundle exec rake db:migrate before pointing the service at the new directory. The Redmine upgrade guide describes the full procedure.

Frequently asked questions

Can I use MySQL or MariaDB instead of PostgreSQL?

MySQL 8.0 to 8.4 is supported; set adapter: mysql2, create the database with CHARACTER SET utf8mb4 and keep transaction_isolation: "READ-COMMITTED" in database.yml, as the installation guide requires. You also need the MySQL development headers to build the driver. MariaDB is not in Redmine's list of supported databases.

Why Puma and not Passenger?

Older tutorials used Phusion Passenger as an Apache module. The current Redmine guide tests the installation with Puma, and running Puma under systemd behind a reverse proxy needs no third-party repository on the RHEL 9 family.

How do I install a plugin?

Copy the plugin into /opt/redmine/plugins as the redmine user, run bundle install and RAILS_ENV=production bundle exec rake redmine:plugins:migrate, then restart the service. Check that the plugin states support for Redmine 7.0 first, because the move to Rails 8.1 breaks plugins written for older releases.

The upload of a large attachment fails. What do I change?

Two limits apply: Maximum attachment size under Administration > Settings > Files, and client_max_body_size in the nginx server block. Raise both and reload nginx.

Share story:

Continue reading other guides on How VPS.