Production on a single VPS with Docker Compose: minimal but reliable
I have written before about production deployment on a VPS: SSH, firewall, systemd, nginx, HTTPS and backups. Back then, to the question "do I need Docker?", I answered "not at the start".
Now I want to take the second half of that question: if you have decided to move to Docker, how do you do it properly on a single server.
Because starting things with docker compose up -d is easy, but that is not production yet. Production means a crashed container comes back, logs do not fill the disk, the site does not drop during a deploy, and the database can be restored.
When Docker is worth it
First, the honest answer: with one language, one service and one database, Docker gives you little. A systemd unit is simpler and faster.
Docker earns its place in two situations.
The first is multiple services. Backend, frontend, database, cache, a worker for background jobs. Managing each with its own systemd file gets tangled quickly.
The second is environment reproducibility. Your laptop and the server run the same image. The "works on my machine" problem disappears.
If neither applies to you, bookmark this and take the simple road.
A starting compose file
Here is a minimal but complete stack that runs on one server:
services:
db:
image: postgres:17-alpine
restart: unless-stopped
environment:
POSTGRES_PASSWORD_FILE: /run/secrets/db_password
POSTGRES_DB: app
volumes:
- db-data:/var/lib/postgresql/data
secrets:
- db_password
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5
api:
image: ghcr.io/madrimovdev/app-api:${TAG}
restart: unless-stopped
depends_on:
db:
condition: service_healthy
environment:
DATABASE_URL: postgres://postgres@db:5432/app
healthcheck:
test: ["CMD", "curl", "-fsS", "http://localhost:3000/health"]
interval: 15s
timeout: 3s
retries: 3
start_period: 20s
volumes:
db-data:
secrets:
db_password:
file: ./secrets/db_passwordThere are three important things in this file. Let us take them one at a time.
Healthchecks — the most commonly skipped part
restart: unless-stopped brings a container back when it dies. But the worst failure is not a dead container — it is one that is alive but not working.
The process is running, the port is open, but the database connection dropped and every request returns an error. As far as Docker is concerned everything is fine, because the process is alive.
That is exactly what a healthcheck catches. And your /health endpoint has to do a real check — at minimum one cheap query against the database:
app.get('/health', async (c) => {
await db.execute(sql`select 1`)
return c.json({ ok: true })
})If /health simply returns { ok: true }, it only proves the HTTP server is alive — which tells you almost nothing.
The second important piece is depends_on with condition: service_healthy. Without it the API starts before the database is ready, the migration fails, and the container falls into a restart loop.
start_period matters too: the application needs time to boot, and healthcheck failures during that window should not count.
Logs will fill your disk
This is the most common and most surprising failure: months later the server stops, and the cause is log files filling the disk.
Docker does not cap log size by default. You have to add it per service:
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"At most 30 MB per service. Skipping this is scheduling yourself a phone call in the middle of a future night.
Do not put secrets in environment
A password inside environment is visible via docker inspect and stored in the container's metadata.
Compose has file-based secrets, and the example above uses them. Many images understand _FILE-suffixed variables — POSTGRES_PASSWORD_FILE, for instance.
The same pattern is easy to adopt in your own application:
const dbPassword = process.env.DB_PASSWORD_FILE
? await readFile(process.env.DB_PASSWORD_FILE, 'utf8')
: process.env.DB_PASSWORDSecret files should sit on the server with 600 permissions and must never enter git.
Deploying without downtime
The simplest deploy is docker compose pull && docker compose up -d. The problem is that the old container goes down, the new one comes up, and in between the site is unavailable for a few seconds.
To get that to zero on a single server you need a reverse proxy in front. I use Traefik — it sees the containers itself and only routes traffic to a new one once it is healthy.
The minimal wiring:
api:
labels:
- traefik.enable=true
- traefik.http.routers.api.rule=Host(`api.example.com`)
- traefik.http.services.api.loadbalancer.server.port=3000With the proxy and healthchecks working together, a deploy goes like this: the new container starts, passes its healthcheck, the proxy shifts traffic to it, the old one shuts down. The user notices nothing.
If Traefik feels like too much, there is a simpler path: keep nginx outside the containers and swap between two ports. But that is manual work with a high chance of error.
Where to run migrations
The most common mistake is running migrations on application startup. If two copies come up, both start migrating at the same time.
The right way is a separate one-shot step:
docker compose run --rm api bun run db:migrate
docker compose up -dIf the migration succeeds, the deploy continues; if not, it stops and the old version keeps serving. That is exactly the behaviour you want.
Backups are the most important part
Getting everything else right and forgetting backups is the most expensive mistake available.
The minimal solution: a daily dump, a copy somewhere off the box, and a restore test.
#!/bin/bash
set -euo pipefail
STAMP=$(date +%F)
docker compose exec -T db pg_dump -U postgres app | gzip > "/backup/app-$STAMP.sql.gz"
find /backup -name 'app-*.sql.gz' -mtime +14 -deleteThe third item is the most important and the most skipped. An untested backup is not a backup, it is a hope. Restore it into an empty database at least once and compare the numbers.
What not to do
A few things are tempting and actively harmful on a single server.
Running the database in a container without a volume. Forget the volume, and the first docker compose down -v erases everything.
Mounting your code as a volume. Convenient locally, but in production it makes it unclear what the image actually contains. In production, use the image only.
The `latest` tag. You do not know which version is running and you cannot roll back. Tag every deploy explicitly.
Cramming everything into one container. Database, application and nginx in a single image is not using Docker, it is misusing it.
Final checklist
Before calling the stack production, verify:
- Does every service have
restart: unless-stopped? - Does every service have a real
healthcheck, not just a port probe? - Are log sizes capped?
- Are secrets in files rather than
environment? - Do migrations run as a separate step?
- Are backups automatic and has a restore been tested?
- Does everything come back on its own after a reboot? (Easy to test:
sudo reboot.)
Do test that last one at least once. Living on the belief that it should work in theory is how you end up with an unexpected night.