Deploy Strapi on a VPS: the complete guide

On your workstation, generate the project with the official command npx create-strapi-app@latest my-cms --dbclient=postgres. Choose TypeScript if your team is comfortable with it. Initialise the Git repository, push it to your forge, then clone it on the VPS into /srv/my-cms. Everything that follows is prepared in that repository and not on the server: the VPS should only ever receive code that is already versioned.

In config/database.js — or config/database.ts in TypeScript — the exported function receives env and returns a connection object. Declare client: 'postgres', then six keys read from the environment inside the connection sub-object: host: env('DATABASE_HOST', '127.0.0.1'), port: env.int('DATABASE_PORT', 5432), database: env('DATABASE_NAME', 'strapi'), user: env('DATABASE_USERNAME', 'strapi'), password: env('DATABASE_PASSWORD', '') and ssl: env.bool('DATABASE_SSL', false). The second argument of env() is only a development fallback: no real value belongs in this file, it goes into Git.

Strapi refuses to start in production without APP_KEYS, API_TOKEN_SALT, ADMIN_JWT_SECRET, JWT_SECRET and TRANSFER_TOKEN_SALT. Generate each one with openssl rand -base64 32; APP_KEYS expects several, separated by commas, so produce at least two. Write them into /srv/my-cms/.env on the VPS — never into Git — together with DATABASE_HOST, DATABASE_NAME, DATABASE_USERNAME, DATABASE_PASSWORD, NODE_ENV=production and URL=https://cms.your-domain.com. A missing key means a refusal to start, not a warning.

Two stages are enough to keep the production image light. The builder stage starts from node:20-alpine, sets WORKDIR /app, copies package*.json, runs npm ci, copies the rest of the code, then compiles the admin with NODE_ENV=production npm run build. The runner stage starts again from the same base image and copies only three things from builder: the build folder, node_modules and package.json. Finish with EXPOSE 1337 and a CMD that calls npm run start — that is the start script Strapi installs, do not try to launch a server file by hand. If the build dies of OOM, set NODE_OPTIONS=--max-old-space-size=4096 before npm run build.

The file declares two services and one named volume. The postgres service uses the postgres:16-alpine image, receives POSTGRES_DB, POSTGRES_USER and POSTGRES_PASSWORD in its environment block, mounts the pgdata volume on /var/lib/postgresql/data and runs with restart: unless-stopped. The strapi service builds from the local Dockerfile with build: ., reads its variables through env_file: .env, declares depends_on: postgres, mounts ./public/uploads on /app/public/uploads and publishes its port with ports: 127.0.0.1:1337:1337. That binding on the loopback interface is the important point: Nginx becomes the only public entry point, and port 1337 is never exposed to the outside. A redis service remains optional, for session caching or processing queues.

Run docker compose build, then docker compose up -d. Follow the startup with docker compose logs -f strapi. Strapi applies its schema migrations on first start as soon as NODE_ENV=production is set. Expect two to five minutes: building the React admin is by far the slowest step. Wait for the Strapi started successfully line before going further.

Create the vhost /etc/nginx/sites-available/cms.your-domain.com. It listens with listen 80 on server_name cms.your-domain.com, carries a client_max_body_size 50M — indispensable for media uploads — and a single location / block that does proxy_pass http://127.0.0.1:1337. Add the four headers Strapi expects behind a proxy: Host, X-Real-IP, X-Forwarded-For and X-Forwarded-Proto, each set by a proxy_set_header directive. Enable the vhost with a symbolic link into sites-enabled, then validate and reload with nginx -t && systemctl reload nginx.

Obtain the certificate with certbot --nginx -d cms.your-domain.com: Certbot rewrites the vhost to redirect HTTP to HTTPS. Then check that URL=https://cms.your-domain.com really is in the .env, with no trailing slash. That variable is what Strapi uses to build media links and admin redirects; without it, uploaded files come out with wrong addresses and the admin panel misbehaves behind the proxy. Restart the container after any change to the .env: variables are read at startup.

Open https://cms.your-domain.com/admin and create the first administrator account — Strapi asks for it on first access and will not ask again. Then check three things: docker compose ps shows both containers in the running state, the public API answers on /api, and uploading a test file from the media library succeeds. A 502 Bad Gateway at this stage almost always means a stopped strapi container, or one still building: read docker compose logs strapi before touching Nginx.

On the VPS, mkdir -p /srv/backups/strapi. Keep this folder outside the Git repository and outside any path mounted into a container: a dump should never end up in an image or in a release.

docker compose ps gives the exact name, of the form my-cms-postgres-1. It derives from the project folder name: do not copy it from a guide, read it on your own machine. A backup script aimed at a container that does not exist fails silently once it is in the cron.

A single line is enough: docker exec my-cms-postgres-1 pg_dump -U strapi strapi | gzip > /srv/backups/strapi/strapi-$(date +%Y%m%d).sql.gz. The pg_dump runs inside the container, compression and writing happen on the host. Run it once by hand and check the size of the file produced: a dump of a few bytes signals an authentication error swallowed by the pipe.

Add find /srv/backups/strapi -name '*.sql.gz' -mtime +7 -delete right after. Without that line, the disk fills up within a few weeks: it is the most mundane failure of a daily backup — the database goes down because the backup saturated the volume.

Put both commands in a /etc/cron.daily/strapi-backup script, with #!/bin/bash on the first line and a chmod +x to make it executable. Add an rsync to external storage, or a copy to the same S3 bucket as the media. A backup that stays on the machine it backs up protects nothing; test a full restore at least once before relying on it.