Publishing, checked 2026-10-17
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.5.0,12.5,12.4.1 - 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. Past the 30 day grace period, a missing license key means SSO login no longer works and custom permission rules are ignored; the deploy still starts. source for this reverse-proxy note
Release timeline
| Version | Date | Breaking | What changed | Source |
|---|---|---|---|---|
v12.5.0 | 2026-10-07 | Yes | Fixed TFA enforcement to use effective permissions, hardened license renewal, removed ip-matching so malformed subnets are rejected, and removed CACHE_SCHEMA_MAX_ITERATIONS. | source for release v12.5.0 |
v12.4.1 | 2026-09-23 | No | Fixed reading the folders endpoint as a non-admin user. | source for release v12.4.1 |
v12.4.0 | 2026-09-22 | Yes | Updated MapLibre to 6.9.0 (maps need WebGL2) and Unhead to 3.x, enforced read permissions for updateByQuery/deleteByQuery, and added a Mailtrap email transport. | source for release v12.4.0 |
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 |
If it is not coming up
- ECONNREFUSED / ENOTFOUND / connection to server at "postgres" port 5432 failed
- 502 Bad Gateway (Traefik)
- 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-10-17. Every row links the page it came from. Upstream changes without telling anyone, so check the source link before you rely on a value.