How to Deploy Directus on a VPS

#Install Directus (Docker Compose)

Directus publishes a Compose example with PostgreSQL (the PostGIS image), Redis for caching, and Directus itself. The version below follows it, with these changes:

• The image is pinned. Upstream recommends pinning a version for production, and 12.4.1 is the current release.
• Secrets are generated instead of placeholders.
• The port is bound to loopback.
• Named volumes replace bind mounts, so the container's node user owns its upload directory.
• The Directus health check calls 127.0.0.1 instead of localhost. Inside the 12.4.1 image, localhost resolved to the IPv6 address, where Directus wasn't listening. With upstream's line the container stayed unhealthy in our test even though it was serving requests.

First, the secrets. The if guard makes the block safe to run twice:

copymkdir -p ~/directus && cd ~/directus
if [ ! -f .env ]; then
  cat > .env <<EOF
DB_PASSWORD=$(openssl rand -hex 24)
SECRET=$(openssl rand -hex 32)
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=$(openssl rand -base64 18 | tr -d '/+=')
PUBLIC_URL=https://directus.example.com
EOF
fi
chmod 600 .env
grep ADMIN_ .env

Write down the admin password it prints. Change ADMIN_EMAIL and PUBLIC_URL to your real values. SECRET signs access tokens, so treat it like a password.

copycd ~/directus
cat > docker-compose.yml <<'YAML'
services:
  database:
    image: postgis/postgis:17-3.5
    restart: unless-stopped
    volumes:
      - db_data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: directus
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: directus
    healthcheck:
      test: ["CMD", "pg_isready", "--host=localhost", "--username=directus"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_interval: 5s
      start_period: 30s

  cache:
    image: redis:7
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "[ $$(redis-cli ping) = 'PONG' ]"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_interval: 5s
      start_period: 30s

  directus:
    image: directus/directus:12.4.1
    restart: unless-stopped
    ports:
      # Loopback only: Caddy is the public entry point.
      - "127.0.0.1:8055:8055"
    volumes:
      - uploads:/directus/uploads
      - extensions:/directus/extensions
    depends_on:
      database: { condition: service_healthy }
      cache: { condition: service_healthy }
    healthcheck:
      test: ["CMD-SHELL", "wget --spider -q http://127.0.0.1:8055/server/ping || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_interval: 5s
      start_period: 30s
    environment:
      SECRET: ${SECRET}
      DB_CLIENT: "pg"
      DB_HOST: "database"
      DB_PORT: "5432"
      DB_DATABASE: "directus"
      DB_USER: "directus"
      DB_PASSWORD: ${DB_PASSWORD}
      CACHE_ENABLED: "true"
      CACHE_AUTO_PURGE: "true"
      CACHE_STORE: "redis"
      REDIS: "redis://cache:6379"
      ADMIN_EMAIL: ${ADMIN_EMAIL}
      ADMIN_PASSWORD: ${ADMIN_PASSWORD}
      PUBLIC_URL: ${PUBLIC_URL}

volumes:
  db_data:
  uploads:
  extensions:
YAML

Bring it up and wait for the health checks:

copycd ~/directus
docker compose up -d --wait
docker compose ps

The liveness endpoint answers pong once the HTTP server is running:

copycurl -s http://127.0.0.1:8055/server/ping; echo

ADMIN_EMAIL and ADMIN_PASSWORD are only used to create the first admin when the database is empty. Without them, Directus would show an onboarding screen for the first admin on first visit. Setting them means nobody else can claim the instance before you do. Changing them later has no effect, so change the password from the Studio instead.

#HTTPS + domain

Point an A record for directus.example.com at the server, then proxy it with Caddy. The steps are in Automatic HTTPS with Caddy:

directus.example.com {
    reverse_proxy 127.0.0.1:8055
}

PUBLIC_URL must match this address exactly. Directus uses it for links in emails, for OAuth redirects and for asset URLs. Open https://directus.example.com and sign in with the admin credentials from .env.

#Securing it

• Change the admin password in the Studio after the first login, then remove ADMIN_PASSWORD from .env. It is only read at bootstrap.
• Review the Public policy. Directus's access control has a Public role for unauthenticated requests. Grant it read access only to the collections you really want public, such as published articles for a CMS front end.
• Use static tokens for machine clients. Give each integration its own user with the smallest set of permissions and a static token. Don't reuse your admin login.
• Keep 8055 on loopback. Docker-published ports bypass ufw.
• Health endpoint: /server/ping is unauthenticated and fine for an uptime monitor. /server/health checks dependencies, needs a token, and costs more to run.

#Backups

Your content lives in PostgreSQL. Uploaded files live in the uploads volume. A logical dump is safe while the stack runs:

copycd ~/directus
mkdir -p backups
docker compose exec -T database pg_dump -U directus -d directus | gzip > backups/directus-db-$(date +%F).sql.gz
docker run --rm -v directus_uploads:/data:ro -v "$PWD/backups":/backup alpine \
  tar czf /backup/directus-uploads-$(date +%F).tar.gz -C /data .
ls -lh backups/

Compose prefixes the volume name with the project directory. Check it with docker volume ls. Copy backups/ and .env off the server. Without SECRET and the database password, the dump restores data but not a working instance. If you install extensions, back up the extensions volume as well.

#Upgrades

Upstream's instructions are short: change the image tag and restart. Directus runs all database migrations automatically on startup. Upstream also publishes a list of breaking changes with every release, and you should read it before every upgrade. Releases come out roughly once a month.

copycd ~/directus
# after editing the directus/directus tag in docker-compose.yml:
docker compose pull
docker compose up -d --wait

Take the pg_dump backup first. Migrations run forward only, so the dump is your way back.

#Troubleshooting

directus never turns healthy. Run docker compose logs directus --tail 100. The usual cause is a database authentication error. PostgreSQL reads POSTGRES_PASSWORD only when its volume is first created, so a later change in .env leaves the two out of sync.

Uploads fail with permission errors. You switched the volumes to bind mounts (./uploads). The container runs as the unprivileged node user and can't write to a directory owned by root. Use named volumes as above, or chown the directory to the container's UID.

Links in emails or file URLs point to the wrong host. PUBLIC_URL is wrong. Fix it in .env and run docker compose up -d.

The admin login fails on a fresh install. Check for special characters in ADMIN_PASSWORD that a shell or YAML parser might have changed. The generator above removes /, + and = for that reason.

#Verification + next steps

You're done when:

• https://directus.example.com loads over a valid certificate;
• you can sign in and have changed the admin password;
• a test collection survives docker compose restart;
• a dated pg_dump exists off the server.

From there, model your first collections, set the Public policy, and connect a front end with the SDK. To compare backends, see Appwrite on a VPS and Supabase on a VPS. For a spreadsheet-style UI over data, see NocoDB on a VPS. For ranked hosts, see Best VPS for databases.