Publishing, checked 2026-09-07
Directus: Docker configuration reference
Self-hosted headless CMS and instant REST/GraphQL API layer over an existing SQL database.
At a glance
- Image:
directus/directus - Tags:
latest,12,12.3.1,12.3,12.2.0 - Licence: Monospace Sustainable Core License (MSCL-1.0-GPL)
- Source: https://github.com/directus/directus
- Docs: https://directus.com/docs
Ports
| Port | What listens | Source |
|---|---|---|
8055 | HTTP listener for the API and the Data Studio app. Route the proxy here. | source for port 8055 |
Environment variables
| Variable | Required | What it does | Example | Source |
|---|---|---|---|---|
PUBLIC_URL | No | URL where the API is reached on the web. Used for OAuth redirects, forgot-password emails and publicly-accessible logos, and must be a qualified URL to use licensing or SSO. | https://cms.example.com | source for PUBLIC_URL |
SECRET | No | Secret string used for signing. Defaults to a random value if unset, so set it explicitly to keep sessions valid across redeploys. | openssl rand -hex 32 | source for SECRET |
DB_CLIENT | Yes | Database client. One of pg, mysql, oracledb, mssql, sqlite3 or cockroachdb. | pg | source for DB_CLIENT |
ADMIN_EMAIL | No | Email of the first admin user, created automatically when the project bootstraps. | admin@example.com | source for ADMIN_EMAIL |
LICENSE_KEY | No | License key activated against the Directus licensing service. Since v12.0.0, an instance without one runs on the Core tier and loses SSO and custom permission rules after a grace period. | DXXXX-XXXXX-XXXXX-XXXXX-XXXXC | source for LICENSE_KEY |
Volumes that must persist
| Path | What is in it | Source |
|---|---|---|
/directus/uploads | Uploaded files stored on local disk when no S3-compatible storage adapter is configured. | source for /directus/uploads |
Behind a reverse proxy
- Route the domain to container port 8055. source for this reverse-proxy note
- Set PUBLIC_URL to the externally reachable URL. Left at its default, OAuth redirects, password-reset emails and generated asset URLs point at the wrong address. source for this reverse-proxy note
- Directus 12 enforces licensing on the Core tier by default. Past the 30 day grace period, a missing license key silently drops SSO login and custom permission rules rather than failing the deploy. source for this reverse-proxy note
Release timeline
| Version | Date | Breaking | What changed | Source |
|---|---|---|---|---|
v12.3.1 | 2026-08-25 | No | Added emitter listener-count methods and fixed a WebSocket heartbeat listener leak and GraphQL fragments returning null fields. | source for release v12.3.1 |
v12.3.0 | 2026-08-18 | Yes | Fixed leaking storage connections that could make every asset request return a permission error until restart, and changed pm2 invocation in the Docker image's entrypoint. | source for release v12.3.0 |
v12.2.0 | 2026-07-29 | Yes | Restricted minimal app access to fewer settings fields and replaced the TinyMCE WYSIWYG editor with Tiptap, which can lock existing content read-only pending confirmation. | source for release v12.2.0 |
v12.1.1 | 2026-07-01 | No | Dependency bump only, updating vite to 8.1.2. | source for release v12.1.1 |
v12.1.0 | 2026-07-01 | Yes | Removed the /utils/hash/generate and /utils/hash/verify endpoints and limited sensitive system mutations to single use. | source for release v12.1.0 |
If it is not coming up
- ECONNREFUSED / ENOTFOUND / connection to server at "postgres" port 5432 failed
- 502 Bad Gateway (Traefik) — build succeeds and container runs, but your-domain.com returns 502 Bad Gateway
- Coolify volume data lost after redeploy / a new empty volume is created every deploy
- Migrating off Supabase to self-hosted Postgres on Coolify
Read from the upstream documentation, repository and container registry by Keita Emsden on 2026-09-07. Every row links the page it came from. Upstream changes without telling anyone, so check the source link before you rely on a value.