Analytics cookies only (Google Analytics, PostHog). No ad networks, no cross-site tracking. See our privacy policy.
Updated Nov 2026
verified on Ubuntu 26.04 · Nov 2026Self-host Redmine 7.0.3 with PostgreSQL on a 2 GB VPS — pinned tags, generated secrets, loopback-only port, Caddy HTTPS, replacing the default admin/admin login, backups.
Redmine is a long-running open-source project management and issue tracking application: multiple projects and subprojects, per-project wikis and forums, time tracking, role-based access control, a calendar and Gantt charts, and a repository browser for version control. It is a Ruby on Rails app, licensed GPL-2.0-or-later, and it runs against PostgreSQL, MySQL or SQL Server. The official Docker image falls back to SQLite when no database is configured, which its own Docker Hub page calls "not for multi-user production use", so this guide uses PostgreSQL. It is rated 2 / 5 to deploy.
Redmine is a plain issue tracker without sprint-board polish, which is the point for many teams. For a Jira replacement see Jira alternatives; Kanboard is a much lighter kanban board (about 52 MB idle in our catalog measurement), Leantime (with its deploy guide) is a sprint-style tracker, and OpenProject is a heavier peer.
Security note before you start. A fresh Redmine database ships with an
administrator named admin whose password is admin; upstream's install page
tells you to log in with that account. Anyone who finds the address before you
change the password owns the tracker. This guide therefore puts HTTPS in front
first and replaces the password immediately afterwards, in the same pass.
Upstream publishes no RAM minimum for Redmine; its install page lists
supported operating systems, Ruby and database versions and optional
components, not memory. What we measured: on a GCP e2-standard-2 (Ubuntu
26.04, Docker 29.9.3, November 2026) the stack of Redmine 7.0.3 and
PostgreSQL 17 idled at about 235 MB of RAM (Redmine about 199 MB, PostgreSQL about 36 MB; Caddy adds
about 14 MB), and docker system df for the whole host (including the Caddy and Alpine images
used by later steps) showed about 1.7 GB of Docker disk
(1.67 GB of images, 51 MB of volumes). That is the idle floor with
no projects, plugins or repositories; attachments, and the Rails process under
real traffic, grow from there. A 2 GB server leaves room for the OS and Caddy;
go larger when you add plugins.
Install Docker and the Compose plugin by following Docker and Compose on Ubuntu, and confirm the versions:
docker --version
docker compose version
Open SSH plus the two ports Caddy will use. Redmine itself gets no public port:
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force enable
Docker publishes container ports by editing the firewall directly, which
bypasses ufw rules. That is why the compose file below binds Redmine's port
to 127.0.0.1 instead of relying on ufw to block it.
Paid link — we earn a commission if you shop through it.
Generate the database password and the Rails secret. The image reads
SECRET_KEY_BASE, which the Docker Hub page says signs session cookies; if it
is unset the image generates one inside the container. The block only writes
.env if it does not exist, so re-running it cannot change the password under
a live database or invalidate every session:
mkdir -p ~/redmine && cd ~/redmine
if [ ! -f .env ]; then
echo "DB_PASSWORD=$(openssl rand -hex 16)" > .env
echo "SECRET_KEY_BASE=$(openssl rand -hex 32)" >> .env
fi
chmod 600 .env
Now the compose file: the one we verified, with the web port bound to loopback and both images pinned.
Redmine's mail settings live in config/configuration.yml, which the image
ships only as configuration.yml.example and which is not in any volume (only
files is). Create it on the host from the image's own example and mount it,
so it survives upgrades and goes into the backup:
cd ~/redmine
[ -f configuration.yml ] || docker run --rm --entrypoint cat redmine:7.0.3 config/configuration.yml.example > configuration.yml
cd ~/redmine
cat > docker-compose.yml <<'EOF'
services:
redmine:
image: redmine:7.0.3
restart: unless-stopped
ports:
- "127.0.0.1:3000:3000"
environment:
REDMINE_DB_POSTGRES: db
REDMINE_DB_USERNAME: redmine
REDMINE_DB_PASSWORD: ${DB_PASSWORD}
REDMINE_DB_DATABASE: redmine
SECRET_KEY_BASE: ${SECRET_KEY_BASE}
volumes:
- redmine_files:/usr/src/redmine/files
- ./configuration.yml:/usr/src/redmine/config/configuration.yml
depends_on:
db:
condition: service_healthy
db:
image: postgres:17
restart: unless-stopped
environment:
POSTGRES_USER: redmine
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_DB: redmine
volumes:
- db_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U redmine -d redmine"]
interval: 3s
timeout: 3s
retries: 20
volumes:
redmine_files:
db_data:
EOF
REDMINE_DB_POSTGRES names the database host (here the db service). The
image's entrypoint turns these variables into config/database.yml on first
start, then runs rake db:migrate on every start unless
REDMINE_NO_DB_MIGRATE is set. The redmine_files volume is
/usr/src/redmine/files, where Redmine stores uploaded attachments; the
image declares it as a volume itself, so it is the second thing, after
PostgreSQL, that a backup must cover.
Start the stack and wait for Redmine to answer on the loopback port:
cd ~/redmine
docker compose up -d
out=000
for i in $(seq 1 60); do
out=$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:3000/)
[ "$out" = "200" ] && break
sleep 5
done
docker compose ps
echo "redmine over loopback: $out"
[ "$out" = "200" ] || false
The first start creates the schema (the entrypoint runs rake db:migrate), so
allow a minute or two. It does not load Redmine's default trackers,
statuses, priorities and workflows; the first-run step below does that.
Create an A record for your hostname (say redmine.example.com) pointing
at the server. With no domain yet, an sslip.io name resolves to your
server's IP with no DNS setup, which is what this guide uses so every command
runs as written:
DOMAIN="redmine.$(curl -4s https://ifconfig.me).sslip.io"
echo "$DOMAIN"
Keep this shell session open (or re-run the line) for the rest of the guide, and replace the value with your real hostname when you have one. Run Caddy as a container on the host network. It obtains and renews a Let's Encrypt certificate on its own (see Automatic HTTPS with Caddy) and proxies to the loopback port:
mkdir -p ~/caddy
cat > ~/caddy/Caddyfile <<EOF
$DOMAIN {
reverse_proxy 127.0.0.1:3000
}
EOF
docker rm -f caddy >/dev/null 2>&1 || true
docker run -d --name caddy --restart unless-stopped --network host \
-v ~/caddy/Caddyfile:/etc/caddy/Caddyfile:ro -v caddy_data:/data caddy:2
Caddy's reverse_proxy passes Host through and sets X-Forwarded-For,
X-Forwarded-Proto and X-Forwarded-Host, so the one-line Caddyfile is
complete. Check that HTTPS answers with a trusted certificate, retrying while
the certificate is issued:
out=000
for i in $(seq 1 24); do
out=$(curl -s -o /dev/null -w '%{http_code} %{ssl_verify_result}' "https://$DOMAIN/") && [ "${out%% *}" = "200" ] && break
sleep 5
done
echo "redmine over HTTPS and certificate check: $out"
[ "${out%% *}" = "200" ] || false
A second number of 0 means the certificate verified.
The admin account exists from the first start: login admin, password
admin. With HTTPS up, replace that password now, before you share the
address. In a browser, open your hostname, choose Sign in, log in as
admin / admin. The migration ForcePasswordResetDuringSetup marks an
admin who has never logged in as needing a new password, so Redmine
redirects you straight to a Change password form; set a strong one there.
The check below shows that flag on your install:
cd ~/redmine
docker compose exec -T db psql -U redmine redmine -Atc "select login, must_change_passwd from users where login='admin'"
t means the forced change is pending.
If you would rather not type the default password into a browser at all, you
can instead set a generated one from the command line. This runs a Rails script inside the
container that sets the password on the admin user and stores the new value
in a file only you can read:
cd ~/redmine
ADMIN_PW="$(openssl rand -hex 12)"
docker compose exec -T -e ADMIN_PW="$ADMIN_PW" redmine bin/rails runner '
u = User.find_by_login("admin")
u.password = u.password_confirmation = ENV.fetch("ADMIN_PW")
u.must_change_passwd = false
u.save!
puts "admin password updated"
'
( umask 077; echo "$ADMIN_PW" > ~/redmine/admin-password.txt )
Check that the default login is rejected and the new one is accepted. A failed
login re-renders the form with 200; a successful one redirects with 302:
login() {
jar=$(mktemp)
tok=$(curl -s -c "$jar" "https://$DOMAIN/login" | grep -o 'name="authenticity_token" value="[^"]*"' | head -1 | sed 's/.*value="//;s/"$//')
curl -s -b "$jar" -c "$jar" -o /dev/null -w '%{http_code}' \
--data-urlencode "authenticity_token=$tok" --data-urlencode "username=admin" \
--data-urlencode "password=$1" "https://$DOMAIN/login"
rm -f "$jar"
}
old=$(login admin)
new=$(login "$(cat ~/redmine/admin-password.txt)")
echo "old admin/admin: $old (want 200) new password: $new (want 302)"
[ "$old" = "200" ] && [ "$new" = "302" ] || false
After you sign in, the Administration page offers Load the default
configuration (the notice appears while none of the default data is loaded;
we found the trackers, statuses, enumerations and workflow tables empty after a
fresh start). Choose your language and click it: the loader creates the
default roles, trackers, issue statuses and workflow, which a new project
needs before anyone can file an issue. Then, in the browser under Administration > Settings > General, set the
Host name and path to your hostname and Protocol to HTTPS, so links
in the mail Redmine sends are correct. Under Administration > Settings >
Authentication, consider turning off self-registration if only your team
should sign up.
Redmine's state is in four places, and a backup needs all of them. In this setup:
pg_dump is
the portable copy.redmine_files), which holds attachments. A database
dump without it leaves every attachment link dead.configuration.yml, your mail settings, bind-mounted from the app
directory..env and docker-compose.yml, which are not in any volume. Keep
SECRET_KEY_BASE: losing it logs everyone out.Upstream's upgrade page says the same in one line: back up your database and
your files directory. Dump the database with the stack running, then archive
the files volume:
cd ~/redmine
mkdir -p ~/redmine-backup
docker compose exec -T db pg_dump -U redmine redmine | gzip > ~/redmine-backup/redmine-$(date +%F).sql.gz
v="$(basename "$PWD")_redmine_files"
docker run --rm -v "$v":/v:ro -v ~/redmine-backup:/b alpine tar czf "/b/redmine-files-$(date +%F).tgz" -C /v .
cp .env docker-compose.yml configuration.yml ~/redmine-backup/
ls -la ~/redmine-backup
test -s ~/redmine-backup/redmine-$(date +%F).sql.gz
test -s ~/redmine-backup/redmine-files-$(date +%F).tgz
A fresh install has no attachments yet, so the files archive is only a few
bytes; it grows as people upload. Copy the archives off the server to object storage or another machine on a
schedule; the .env copy holds secrets, so keep it protected. To restore,
bring up an empty stack with the same .env, compose file and
configuration.yml, start only db, load the dump, unpack the files archive
into the new redmine_files volume, then start redmine:
cd ~/redmine
docker compose up -d db
gunzip -c ~/redmine-backup/redmine-DATE.sql.gz | docker compose exec -T db psql -U redmine redmine
docker run --rm -v "$(basename "$PWD")_redmine_files":/v -v ~/redmine-backup:/b alpine tar xzf /b/redmine-files-DATE.tgz -C /v
docker compose up -d
We tested the database half: loading the dump into a scratch database in the running stack gave the same user, settings and migration counts as the live one. We did not test the files half, since a fresh install has no attachments. An untested backup is a guess, so restore into a throwaway server now and then.
Take the backup above first. Upstream's upgrade page (written for installs from
a release archive) says to back up the database and files, move the old
config/database.yml, files and your custom plugins into the new release,
run bundle exec rake db:migrate, clear the cache with
bundle exec rake tmp:cache:clear, restart the app server, and check
Administration > Roles and permissions for any new features. It does not say
whether releases can be skipped, so read the release notes of every version
between yours and the target. With the Docker image the migration is
automatic: the entrypoint runs rake db:migrate on every start (and
rake redmine:plugins:migrate as well if REDMINE_PLUGINS_MIGRATE is set), so
an upgrade is a new tag against the same volumes:
cd ~/redmine
sed -i 's|redmine:7.0.3|redmine:NEW_VERSION|' docker-compose.yml
docker compose pull redmine
docker compose up -d redmine
Move the pin yourself rather than tracking latest. The PostgreSQL tag is a
separate decision: moving majors is a dump and restore, not a new image.
curl returns 000 or 502 right after up -d. The first start runs the
database migration. Follow docker compose logs -f redmine until the web
server reports it is listening on port 3000.
Everyone is logged out after a restart. SECRET_KEY_BASE changed or went
missing; without it the image generates a fresh one inside the container. Keep
it in .env and in your backups.
Redmine sends no mail. Outgoing mail is configured in
configuration.yml (the file you mounted), not in the web UI; edit its
email_delivery section from the example and restart redmine.
Emails contain wrong links. Set Host name and path and Protocol under Administration > Settings > General.
Port 3000 is reachable from the internet. The port line lost its
127.0.0.1: prefix. Fix the compose file, docker compose up -d, then check
that ss -tln | grep 3000 shows 127.0.0.1.
Certificate never issues. That is a Caddy and DNS problem rather than a
Redmine one: confirm the A record resolves and that ports 80 and 443 are
reachable. Look at docker logs caddy.
You are done when https://redmine.example.com loads with a valid
certificate, admin / admin no longer logs in, port 3000 is bound only to
127.0.0.1, and a database dump plus a files archive are landing off the
server.
From here, create a project, define the trackers and roles you need under Administration, and set up outgoing mail. If Redmine turns out to be more tracker than you want, Kanboard is a lighter board and Leantime a sprint-style alternative.
We estimate about 25 minutes of hands-on time for "How to Deploy Redmine on a VPS"; this is an editorial estimate, not a measurement.
The "How to Deploy Redmine on a VPS" guide was verified end-to-end on Ubuntu 26.04 (Nov 2026).