Analytics cookies only (Google Analytics, PostHog). No ad networks, no cross-site tracking. See our privacy policy.
Updated Sep 2026
verified on Ubuntu 26.04 · Sep 2026Self-host Directus, the headless CMS and data platform, on a VPS with Docker Compose, PostgreSQL, Redis and HTTPS. Pinned versions, generated secrets and real backups.
Directus wraps a SQL database with instant REST and GraphQL APIs and a web app called the Studio. It is often used as a headless CMS, as an internal data tool, or as the backend for an app. It doesn't import your data into its own format. It works on the tables in your database, so you can still query them directly.
That puts it in the same space as Appwrite and Supabase, but with a different focus: Directus vs Appwrite covers the trade-off. Read the licence before you commit. Directus is source-available, and the catalog lists it as MSCL-1.0, so check the current terms at directus.io if you run it commercially.
Directus's requirements page gives the minimum for the Directus container as 0.25 vCPU / 512 MB and a recommended minimum of 1 vCPU / 2 GB. On our test box (GCP e2-standard-2, Ubuntu 26.04, November 2026), a Directus + PostgreSQL stack idled at about 240 MB of RAM and used about 1.9 GB of disk.
uploads
volume unless you configure S3-compatible storage.This guide assumes Docker Engine and the Compose plugin are installed. If not, start with Docker & Compose on Ubuntu. Open SSH and the web ports only:
sudo ufw allow OpenSSH
sudo ufw allow 80
sudo ufw allow 443
sudo ufw --force enable
sudo ufw status verbose
Paid link — we earn a commission if you shop through it.
Directus publishes a Compose example with PostgreSQL (the PostGIS image), Redis for caching, and Directus itself. The version below follows it, with these changes:
12.4.1, the release it was verified with.node user owns its
upload directory.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:
mkdir -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.
cd ~/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:
cd ~/directus
docker compose up -d --wait
docker compose ps
The liveness endpoint answers pong once the HTTP server is running:
curl -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.
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.
ADMIN_PASSWORD from .env. It is only read at bootstrap.ufw./server/ping is unauthenticated and fine for an uptime
monitor. /server/health checks dependencies, needs a token, and costs more
to run.Your content lives in PostgreSQL. Uploaded files live in the uploads volume.
A logical dump is safe while the stack runs:
cd ~/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.
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.
cd ~/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.
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.
You're done when:
https://directus.example.com loads over a valid certificate;docker compose restart;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.
We estimate about 30 minutes of hands-on time for "How to Deploy Directus on a VPS"; this is an editorial estimate, not a measurement.
The "How to Deploy Directus on a VPS" guide was verified end-to-end on Ubuntu 26.04 (Sep 2026).