Install Redmine on Debian

Redmine is a free software project manager and bug tracker built on Ruby on Rails, with Gantt charts, a calendar, wiki, forum, time tracking, and repository integration (Git, Subversion, Mercurial, and others). It has been around since 2006, never became SaaS, and remains the right choice when you want project data inside your own infrastructure, without a per-user subscription.

Which version to install

The project releases every six months and maintains three branches simultaneously. In September 2026:

New installation: 7.0.x. One upstream detail that saves headaches: Ruby 4.0.0 through 4.0.3 has a regression that makes wiki rendering very slow, fixed in 4.0.4. If you choose Ruby 4, use 4.0.4 or newer — or stay on 3.3/3.4, which is what distributions ship today.

Distro package or installation from the tarball?

Debian packages Redmine (apt install redmine-pgsql) and that works — but the repository version is usually far behind the latest release, and plugins and themes expect the project's standard file tree. For a server you will maintain for years, the official tarball gives you more control. That is the approach below.

Dependencies

sudo apt update
sudo apt install -y ruby ruby-dev build-essential 
  libpq-dev zlib1g-dev libssl-dev libyaml-dev 
  imagemagick libmagickwand-dev ghostscript 
  git subversion curl postgresql

# confira a versão do Ruby: o Redmine 7.0 aceita de 3.2 a 4.0
ruby -v

The optional components are worthwhile: ImageMagick enables thumbnails and Gantt export to PNG, Ghostscript generates thumbnails of attached PDFs, and Pandoc (3.8.3 or newer) enables previews of .docx, .xlsx, .pptx and .odt in Redmine 7.

Database

PostgreSQL 14 or newer is the project's recommendation:

sudo -u postgres psql -c "CREATE ROLE redmine LOGIN ENCRYPTED PASSWORD 'troque-esta-senha' NOINHERIT VALID UNTIL 'infinity';"
sudo -u postgres psql -c "CREATE DATABASE redmine WITH ENCODING='UTF8' OWNER=redmine;"

Downloading and configuring Redmine

sudo adduser --system --group --disabled-password --home /opt/redmine redmine

cd /tmp
VER=7.0.1
curl -fLO https://www.redmine.org/releases/redmine-${VER}.tar.gz
# confira o SHA-256 publicado na página de download antes de extrair
sha256sum redmine-${VER}.tar.gz

sudo tar xzf redmine-${VER}.tar.gz --strip-components=1 -C /opt/redmine
sudo chown -R redmine:redmine /opt/redmine

Create /opt/redmine/config/database.yml:

production:
  adapter: postgresql
  database: redmine
  host: localhost
  username: redmine
  password: "troque-esta-senha"
  encoding: utf8

Gems, secret key, and migration

cd /opt/redmine

sudo -u redmine bundle config set --local without 'development test'
sudo -u redmine bundle config set --local path 'vendor/bundle'
sudo -u redmine bundle install

sudo -u redmine bundle exec rake generate_secret_token
sudo -u redmine RAILS_ENV=production bundle exec rake db:migrate
sudo -u redmine RAILS_ENV=production REDMINE_LANG=pt-BR bundle exec rake redmine:load_default_data

The REDMINE_LANG=pt-BR loads trackers, roles, priorities, and statuses in Portuguese — if you leave it blank, it prompts you interactively.

Permissions for directories Redmine writes to at runtime:

sudo mkdir -p /opt/redmine/tmp/pdf /opt/redmine/public/plugin_assets
sudo chown -R redmine:redmine /opt/redmine/files /opt/redmine/log /opt/redmine/tmp /opt/redmine/public/plugin_assets
sudo chmod -R 755 /opt/redmine/files /opt/redmine/log /opt/redmine/tmp /opt/redmine/public/plugin_assets

Test before turning it into a service:

sudo -u redmine RAILS_ENV=production bundle exec rails server -b 127.0.0.1 -p 3000

Open http://127.0.0.1:3000 through an SSH tunnel. The initial login is admin / admin — change the password on your first login, before making the service public.

Puma as a systemd service

Create /opt/redmine/config/puma.rb:

directory "/opt/redmine"
environment "production"

bind "unix:///opt/redmine/tmp/puma.sock"
pidfile "/opt/redmine/tmp/puma.pid"
state_path "/opt/redmine/tmp/puma.state"

workers 2
threads 2, 8
preload_app!

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

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

[Service]
Type=simple
User=redmine
Group=redmine
WorkingDirectory=/opt/redmine
Environment=RAILS_ENV=production
ExecStart=/usr/bin/bundle exec puma -C /opt/redmine/config/puma.rb
Restart=always
RestartSec=5
TimeoutStartSec=120

NoNewPrivileges=true
PrivateTmp=false
ProtectSystem=full

[Install]
WantedBy=multi-user.target

Pay attention to PrivateTmp=false: Puma's socket is in /opt/redmine/tmp, and nginx needs to be able to access it.

sudo systemctl daemon-reload
sudo systemctl enable --now redmine
journalctl -u redmine -f

Nginx in front, with TLS

upstream redmine {
    server unix:///opt/redmine/tmp/puma.sock;
}

server {
    listen 443 ssl;
    http2 on;
    server_name projetos.exemplo.com.br;

    ssl_certificate     /etc/letsencrypt/live/projetos.exemplo.com.br/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/projetos.exemplo.com.br/privkey.pem;

    root /opt/redmine/public;
    client_max_body_size 100m;

    # arquivos estáticos direto pelo nginx
    location ~ ^/(assets|plugin_assets)/ {
        expires 1y;
        add_header Cache-Control public;
    }

    location / {
        try_files $uri @app;
    }

    location @app {
        proxy_pass http://redmine;
        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;
    }
}

sudo usermod -aG redmine www-data     # nginx precisa ler o socket
sudo certbot --nginx -d projetos.exemplo.com.br
sudo systemctl reload nginx

The shortcut: Docker

If you just want Redmine running without assembling the Ruby stack by hand:

services:
  db:
    image: postgres:17
    restart: always
    environment:
      POSTGRES_DB: redmine
      POSTGRES_USER: redmine
      POSTGRES_PASSWORD: troque-esta-senha
    volumes:
      - ./pgdata:/var/lib/postgresql/data

  redmine:
    image: redmine:6
    restart: always
    depends_on: [db]
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      REDMINE_DB_POSTGRES: db
      REDMINE_DB_DATABASE: redmine
      REDMINE_DB_USERNAME: redmine
      REDMINE_DB_PASSWORD: troque-esta-senha
      REDMINE_SECRET_KEY_BASE: gere-uma-chave-longa-e-aleatoria
    volumes:
      - ./files:/usr/src/redmine/files
      - ./plugins:/usr/src/redmine/plugins

docker compose up -d

The official image on Docker Hub usually follows the stable branch preceding the latest one — check the available tag before pinning the version, and keep putting nginx in front for TLS.

Backup

Three things, none optional:

# 1. banco
sudo -u postgres pg_dump -Fc redmine > /var/backups/redmine-$(date +%F).dump

# 2. anexos enviados pelos usuários
sudo tar czf /var/backups/redmine-files-$(date +%F).tar.gz -C /opt/redmine files

# 3. configuração
sudo tar czf /var/backups/redmine-conf-$(date +%F).tar.gz -C /opt/redmine config

Restoring only the database and forgetting files/ is the classic mistake: Redmine starts up nicely and every attachment becomes a broken link.

Upgrading

sudo systemctl stop redmine
# backup dos três itens acima ANTES de qualquer coisa

# extraia a nova versão por cima, preservando config/, files/ e plugins/
cd /opt/redmine
sudo -u redmine bundle install
sudo -u redmine RAILS_ENV=production bundle exec rake db:migrate
sudo -u redmine RAILS_ENV=production bundle exec rake tmp:cache:clear

sudo systemctl start redmine

Plugins are the number one cause of stalled upgrades. Disable those incompatible with the new version before running the migration — and read the official RedmineUpgrade when moving to a new major branch.

The original post (April 2017)

Preserved as a record. The scripts below installed Redmine 3.3.2 on Debian 8.7 and must not be used today:

## Redmine 3.3.2 integrado ao ISPConfig3 (Debian 8)
cd /tmp/
wget https://gist.githubusercontent.com/jniltinho/66c64a33d8b0a515c95ea9750f8f69d5/raw/5318d664f213155c7e5a5c5f55e4ef2e078a082c/install_redmine.sh
chmod +x install_redmine.sh
./install_redmine.sh

## Redmine 3.3.2 com nginx, em Debian 8.7 limpo
cd /tmp/
wget https://gist.githubusercontent.com/jniltinho/cb0743ed1ddc1544f644c223d1a0578e/raw/1ccfaba34095920d939b1db2461c52bddbab8ef3/install_redmine_nginx.sh
chmod +x install_redmine_nginx.sh
./install_redmine_nginx.sh

The posts cited in the original version are still online: ISPConfig3 on Debian and the Linux Servers Series.

Links

• Official download · RedmineInstall · RedmineUpgrade
• Here on the blog: The history of Git · Installing Gogs on Ubuntu