How to Install and Setup Redmine on Debian 13

Debian 13 (Trixie) delivers a modern base with updated Ruby packages, native systemd management, and contemporary PostgreSQL database support. Deploying Redmine in a production-oriented configuration involves pairing the Ruby on Rails application runtime with Puma as the application server, PostgreSQL for relational storage, and Nginx as a reverse proxy for handling HTTP client traffic and static assets.

This guide walks through deploying Redmine 6.0 on Debian 13. You will configure PostgreSQL, set up dependencies and database migrations, deploy Puma under systemd, configure Nginx, and complete first-run administrative setup through the web interface.

Prerequisites

• A clean installation of Debian 13 (Trixie) with root-equivalent privileges
• At least 2 GB of RAM (4 GB recommended) and 2 vCPUs for Ruby gem compilation and Rails runtime
• Outbound internet connectivity for downloading Debian packages and Ruby gems
• TCP ports 80 (HTTP) accessible for web browser traffic

Key concepts

Redmine Multi-Tier Architecture

Redmine operates as a multi-tier Ruby on Rails application. Client browsers interact with Nginx on port 80. Nginx handles static file delivery from the public asset directory and proxies dynamic Rails requests to Puma listening locally on port 3000. Puma executes the application code, querying the local PostgreSQL database server.

Application Server vs. Reverse Proxy

While Puma is an efficient concurrent HTTP server for Ruby applications, deploying it behind Nginx provides connection buffering, static asset offloading, request filtering, and an abstraction layer for SSL/TLS termination and custom domain routing.

Gem Bundling and Environment Isolation

Bundler manages Ruby gem dependencies specified in Redmine’s Gemfile. By configuring local bundle settings to omit development, test, and optional rmagick libraries, the installation remains lean, reproducible, and tailored for production execution.

1. Install System Packages, Ruby Runtime, and PostgreSQL

Refresh the APT package repositories and install the required build dependencies, Ruby environment, PostgreSQL database server, Git, and Nginx. Once the system packages are in place, install Bundler to manage Ruby gem dependencies.

First refresh the available package information so the following installation uses the configured repositories.

apt-get update

Install the software packages and supporting libraries needed for this part of the setup. Wait until the package manager finishes before continuing.

apt-get install -y ruby ruby-dev build-essential libpq-dev postgresql postgresql-contrib git curl nginx libyaml-dev zlib1g-dev libssl-dev libreadline-dev libffi-dev

Install the Ruby package named in this command so it is available for the following application setup steps.

gem install bundler --no-document

2. Create and Configure the PostgreSQL Database

Start and enable the PostgreSQL service. Create a dedicated database user named ‘redmine’ protected by a secure password, and create an associated UTF-8 encoded database named ‘redmine’ owned by that user.

Enable automatic startup for the postgresql service, so it will start automatically on boot.

systemctl enable --now postgresql

Create the database account that the application will use rather than connecting as the database administrator.

su - postgres -c "psql -tc \"SELECT 1 FROM pg_roles WHERE rolname='redmine'\" | grep -q 1 || psql -c \"CREATE USER redmine WITH ENCRYPTED PASSWORD 'RedmineSecurePass2026!';\""

Create the application database and assign its owner and character encoding.

su - postgres -c "psql -tc \"SELECT 1 FROM pg_database WHERE datname='redmine'\" | grep -q 1 || psql -c \"CREATE DATABASE redmine WITH OWNER redmine ENCODING 'UTF8';\""

3. Create Redmine System User and Clone Source Code

Create an unprivileged system user named ‘redmine’ with /opt/redmine as its home directory. Clone the stable release branch of Redmine from the official repository into /opt/redmine.

Inspect the current user or filesystem state before proceeding.

id -u redmine >/dev/null 2>&1 || useradd -r -s /bin/bash -d /opt/redmine redmine
if [ ! -d /opt/redmine/.git ]; then
  git clone --branch 6.0-stable --depth 1 https://github.com/redmine/redmine.git /opt/redmine
fi

4. Configure Database and Application Server Dependencies

Configure Redmine’s production database connection in config/database.yml to use PostgreSQL on localhost. Additionally, create Gemfile.local to declare Puma as the application server, and copy the default configuration template.

Write the configuration content shown below into the target file. The complete multi-line input is one terminal action, not separate shell commands.

cat <<'EOF' > /opt/redmine/config/database.yml
production:
  adapter: postgresql
  database: redmine
  host: localhost
  username: redmine
  password: "RedmineSecurePass2026!"
  encoding: utf8
EOF

cat <<'EOF' > /opt/redmine/Gemfile.local
gem 'puma'
EOF

cp /opt/redmine/config/configuration.yml.example /opt/redmine/config/configuration.yml

5. Install Gems, Run Database Migrations, and Load Default Data

Configure Bundler to skip unnecessary development, testing, and optional rmagick gems, then install dependencies. Generate the Rails secret token, execute database schema migrations, load default configuration data, and set correct directory ownership.

Configure Bundler to skip unnecessary development, testing, and optional rmagick gems, then install dependencies. Generate the Rails secret token, execute database schema migrations, load default configuration data, and set correct directory ownership. Run the following command, preserved exactly from the validated recording, and check its result before moving on.

cd /opt/redmine
bundle config set --local without 'development test rmagick'
bundle install
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
chown -R redmine:redmine /opt/redmine
chmod -R 755 /opt/redmine/public /opt/redmine/files /opt/redmine/log /opt/redmine/tmp

6. Create and Start the Redmine Systemd Service

Create a systemd service unit file at /etc/systemd/system/redmine.service to manage Puma as a background daemon. Reload the systemd daemon, enable the service to start at boot, and start it immediately.

Create a systemd service unit file at /etc/systemd/system/redmine.service to manage Puma as a background daemon. Reload the systemd daemon, enable the service to start at boot, and start it immediately. Run the following command, preserved exactly from the validated recording, and check its result before moving on.

BUNDLE_BIN=$(which bundle)
cat <<EOF > /etc/systemd/system/redmine.service
[Unit]
Description=Redmine Application Server (Puma)
After=network.target postgresql.service
Requires=postgresql.service

[Service]
Type=simple
User=redmine
Group=redmine
WorkingDirectory=/opt/redmine
Environment=RAILS_ENV=production
ExecStart=${BUNDLE_BIN} exec puma -b tcp://127.0.0.1:3000 -e production
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now redmine.service

for i in $(seq 1 30); do
  if curl -s http://127.0.0.1:3000 >/dev/null; then
    break
  fi
  sleep 2
done

7. Configure Nginx as a Reverse Proxy

Create an Nginx server block that serves static assets directly from /opt/redmine/public and forwards all dynamic requests to the Puma backend on port 3000. Disable the default Nginx site, enable the new configuration, and restart Nginx.

Write the configuration content shown below into the target file. The complete multi-line input is one terminal action, not separate shell commands.

cat <<'EOF' > /etc/nginx/sites-available/redmine
server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name _;

    root /opt/redmine/public;

    client_max_body_size 32m;

    location / {
        try_files $uri/index.html $uri.html $uri @puma;
    }

    location @puma {
        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;
    }
}
EOF

rm -f /etc/nginx/sites-enabled/default
ln -sf /etc/nginx/sites-available/redmine /etc/nginx/sites-enabled/redmine
nginx -t
systemctl restart nginx

8. Initial Sign In and Administrator Password Initialization

Open the Redmine login page in your browser. Authenticate using the default administrator credentials (admin / admin). On the mandatory first-login password change page, enter the old password and set a secure new administrator password.

Open http://YOUR_IP_ADDRESS/login in your browser.

Replace YOUR_IP_ADDRESS with your server IP, or YOUR_DOMAIN with a domain pointing to your server, as applicable. The video shows the actual lab address, which can differ from yours. Use HTTPS only if it has been configured.

• Enter “admin” in the username field.
• Enter “admin” in the password field.
• Click login.
• Enter “admin” in the password field.
• Enter “RedmineAdmin2026!” in the new password field.
• Enter “RedmineAdmin2026!” in the new password confirmation field.
• Click commit.

9. Create and Verify a New Project

Navigate to the Projects directory and create a new project. Provide a project name, unique identifier, and description, then submit the form to verify project creation.

Open http://YOUR_IP_ADDRESS/projects in your browser.

Replace YOUR_IP_ADDRESS with your server IP, or YOUR_DOMAIN with a domain pointing to your server, as applicable. The video shows the actual lab address, which can differ from yours. Use HTTPS only if it has been configured.

• Click New project.
• Enter “GreenCloud Operations” in the project name field.
• Enter “greencloud-ops” in the project identifier field.
• Enter “Central infrastructure tracking and system operations.” in the project description field.
• Click commit.

10. Configure Application Title in System Administration

Navigate to the Administration console and open the Settings area. Customize the global Application title to ‘GreenCloud Redmine’ and save changes to verify administrative configuration persistence.

Open http://YOUR_IP_ADDRESS/admin in your browser.

Replace YOUR_IP_ADDRESS with your server IP, or YOUR_DOMAIN with a domain pointing to your server, as applicable. The video shows the actual lab address, which can differ from yours. Use HTTPS only if it has been configured.

• Click Settings.
• Enter “GreenCloud Redmine” in the settings app title field.
• Click commit.

How the final setup works

User requests arrive over HTTP on port 80 at Nginx. Nginx directly serves static assets from /opt/redmine/public and proxies dynamic application requests to the Puma application server listening locally on TCP port 3000. Puma runs Redmine as a systemd-managed service under the dedicated unprivileged ‘redmine’ user, communicating with the local PostgreSQL database cluster via TCP port 5432.

Troubleshooting

Nginx returns HTTP 502 Bad Gateway when accessing Redmine

Likely cause: The Puma application server is either starting up, crashed, or failing to bind to 127.0.0.1:3000.

Fix: Check the service status and logs using ‘systemctl status redmine.service’ and ‘journalctl -u redmine.service -e’ to inspect Rails initialization errors.

Database connection refused or authentication failed during rake db:migrate

Likely cause: PostgreSQL service is not running or the credentials in config/database.yml do not match the PostgreSQL redmine role.

Fix: Ensure PostgreSQL is active with ‘systemctl status postgresql’ and verify credentials manually using ‘PGPASSWORD=… psql -h localhost -U redmine -d redmine’.

Web UI displays unstyled pages or 403 Forbidden for stylesheets and scripts

Likely cause: Nginx worker processes (user www-data) lack read or execute traversal permissions for /opt/redmine/public.

Fix: Run ‘chmod 755 /opt/redmine’ and ‘chmod -R 755 /opt/redmine/public’ to ensure the web server can read static assets.

Useful commands

Check Redmine Puma service status

systemctl status redmine.service

View live Redmine Puma journal logs

journalctl -u redmine.service -f

Restart Redmine application server

systemctl restart redmine.service

Inspect Redmine production Rails log

tail -n 50 /opt/redmine/log/production.log

Verify Nginx configuration syntax

nginx -t

Reload Nginx reverse proxy

systemctl reload nginx

Conclusion

You have successfully installed and configured Redmine 6.0 on Debian 13 (Trixie). The application runs as an isolated systemd service powered by Puma, backed by a dedicated PostgreSQL database, and proxied securely through Nginx on port 80.

With initial administrative access established and the default password rotated, you are ready to create user accounts, set up issue tracking workflows, connect version control repositories, and integrate SMTP settings in config/configuration.yml for team email notifications.

• Installed system dependencies, Ruby 3.3 runtime, and PostgreSQL on Debian 13
• Configured a dedicated PostgreSQL user and UTF-8 encoded database for Redmine
• Deployed Redmine 6.0 source code under a dedicated ‘redmine’ system user
• Configured Bundler, compiled production gems, and migrated database schemas
• Configured Puma under systemd and established Nginx as the front-end reverse proxy
• Completed first-run login, changed the administrator password, created a project, and updated system settings through the web UI