Directus Local Development with Docker Compose
Run Directus 12 on your machine with PostgreSQL and Redis, driven by environment variables. Everything below is generic: the compose file contains no values, only ${VAR} references. Real values live in a gitignored .env.
The result is a development stack, not a production deployment. For production, read the Directus self-hosting docs (secrets management, backups, reverse proxy, IP_TRUST_PROXY, storage adapter).
Prerequisites
- Docker Engine 25 or later with Compose 2.20.2 or later (
docker compose version). The health checks below usestart_interval, which older versions reject or ignore. On an older setup delete the threestart_intervallines and the stack still works, only slower to report healthy - A free host port for Directus (8055 is the usual default, set
LOCAL_DIRECTUS_PORTwhen it is taken)
Files
my-project/
├── docker-compose.yml
├── .env # real values, gitignored
├── .env.example # placeholders, committed
├── uploads/ # Directus file storage (bind mount)
├── extensions/ # custom extensions (bind mount)
└── data/database/ # PostgreSQL data (bind mount)
.env.example
Commit this file with placeholders. Copy it to .env and fill it in.
# Image: pin an exact version, do not use "latest". Tested up to 12.4.1.
LOCAL_DIRECTUS_VERSION=12.4.1
LOCAL_DIRECTUS_PORT=8055
# Generate once: openssl rand -hex 32
LOCAL_DIRECTUS_SECRET=<random-64-hex-characters>
# First admin account, created on first start
LOCAL_DIRECTUS_ADMIN_EMAIL=admin@example.com
LOCAL_DIRECTUS_ADMIN_PASSWORD=<local-admin-password>
# Optional static token for that admin (for scripts and MCP in local dev only)
LOCAL_DIRECTUS_ADMIN_TOKEN=<local-static-token>
LOCAL_DB_PASSWORD=<local-database-password>
# Origin of your frontend dev server, for CORS (also enforced for WebSockets since 12.1)
LOCAL_FRONTEND_ORIGIN=http://localhost:3000
# Optional: leave empty for the Core tier
LOCAL_DIRECTUS_LICENSE_KEY=
Add .env, uploads/, data/ to .gitignore.
docker-compose.yml
services:
database:
image: postgis/postgis:17-3.5
environment:
POSTGRES_USER: directus
POSTGRES_PASSWORD: ${LOCAL_DB_PASSWORD:?set LOCAL_DB_PASSWORD in .env}
POSTGRES_DB: directus
volumes:
- ./data/database:/var/lib/postgresql/data
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
healthcheck:
test: ["CMD-SHELL", "[ $$(redis-cli ping) = 'PONG' ]"]
interval: 10s
timeout: 5s
retries: 5
start_interval: 5s
start_period: 30s
directus:
image: directus/directus:${LOCAL_DIRECTUS_VERSION:-12.4.1}
ports:
- "127.0.0.1:${LOCAL_DIRECTUS_PORT:-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: ${LOCAL_DIRECTUS_SECRET:?set LOCAL_DIRECTUS_SECRET in .env}
DB_CLIENT: pg
DB_HOST: database
DB_PORT: "5432"
DB_DATABASE: directus
DB_USER: directus
DB_PASSWORD: ${LOCAL_DB_PASSWORD}
CACHE_ENABLED: "true"
CACHE_AUTO_PURGE: "true"
CACHE_STORE: redis
REDIS: redis://cache:6379
ADMIN_EMAIL: ${LOCAL_DIRECTUS_ADMIN_EMAIL:?set LOCAL_DIRECTUS_ADMIN_EMAIL in .env}
ADMIN_PASSWORD: ${LOCAL_DIRECTUS_ADMIN_PASSWORD:?set LOCAL_DIRECTUS_ADMIN_PASSWORD in .env}
ADMIN_TOKEN: ${LOCAL_DIRECTUS_ADMIN_TOKEN:-}
PUBLIC_URL: http://localhost:${LOCAL_DIRECTUS_PORT:-8055}
WEBSOCKETS_ENABLED: "true"
CORS_ENABLED: "true"
CORS_ORIGIN: ${LOCAL_FRONTEND_ORIGIN:-http://localhost:3000}
# Lets the Studio embed your frontend in an iframe (Live Preview)
CONTENT_SECURITY_POLICY_DIRECTIVES__FRAME_SRC: ${LOCAL_FRONTEND_ORIGIN:-http://localhost:3000}
LICENSE_KEY: ${LOCAL_DIRECTUS_LICENSE_KEY:-}
EXTENSIONS_AUTO_RELOAD: "true"
Notes on the file:
LOCAL_prefix. Compose gives variables exported in your shell precedence over.env, silently. A shell that already exportsDIRECTUS_*for your app (aDIRECTUS_ADMIN_TOKEN, say) would override the stack's value with no warning, and a real credential could end up in a throwaway container. The prefix keeps the stack's variables apart from the app'sDIRECTUS_URLandDIRECTUS_TOKEN.- Loopback port.
127.0.0.1:in the port mapping keeps the stack off your network: the local admin password and static token are throwaway values, and a plain8055:8055would publish them on every interface of the machine. Remove the prefix only when another device has to reach the instance. - Pinned tag.
directus/directus:${LOCAL_DIRECTUS_VERSION}keeps restarts from silently upgrading. Directus 12 enforces licensing and has breaking changes between minor versions, so upgrades must be deliberate. :?guards. Compose stops with the message if a required variable is missing, instead of starting Directus with an emptySECRET.- Health check calls
127.0.0.1, notlocalhost: the image'swgettries the IPv6 address forlocalhostfirst and Directus listens on IPv4 only, so alocalhostprobe reports the container as unhealthy while it works fine. CONTENT_SECURITY_POLICY_DIRECTIVES__FRAME_SRCis what lets Live Preview show your frontend inside the Studio. Without it the browser refuses the iframe. Your frontend must allow the Studio origin as well (Content-Security-Policy: frame-ancestors 'self' <studio-origin>), see the Directus Live Preview guide.ADMIN_*create the first admin on an empty database, so the onboarding screen is skipped. They are ignored once the database already has users.PUBLIC_URLmust match the address you open in the browser. Licensing binds to it on first use and OAuth redirects use it.- PostGIS image is the one the Directus docs use, so geometry field types work. A plain
postgresimage also works if you do not need them. LICENSE_KEYstays empty for local development (Core tier). A license key binds to the project andPUBLIC_URLon first use. Deleting a stack that holds a key without deactivating the license first (Settings → License) strands the activation against the license's activation limit, so never test a production key in a throwaway stack.- Redis is optional for one instance. It is included to match production behavior (cache, rate limits).
Start and Verify
Compose reads .env by itself. Your shell does not, so the curl commands below need the values loaded first: set -a; . ./.env; set +a.
mkdir -p uploads extensions data/database
sudo chown 1000:1000 uploads extensions # Linux: the container user "node" is uid 1000
cp .env.example .env # then edit .env
docker compose up -d
docker compose ps # wait until directus is "healthy"
# Liveness: public, answers "pong" once the HTTP server runs
curl -sS "http://localhost:${LOCAL_DIRECTUS_PORT:-8055}/server/ping"
/server/ping is the right probe. /server/health checks the database, Redis, storage and email, but Directus 12 answers 403 to it without a token.
Dependency check with the admin token (200 with "status": "ok" when the database, Redis, storage and email checks pass):
curl -sS "http://localhost:${LOCAL_DIRECTUS_PORT:-8055}/server/health" \
-H "Authorization: Bearer ${LOCAL_DIRECTUS_ADMIN_TOKEN}"
Then open the Studio in the browser at the PUBLIC_URL and sign in with the admin account.
The Directus container runs as the unprivileged node user (uid 1000). On Linux the bind-mounted uploads/ and extensions/ directories must be writable by that uid, which the chown above does. When they are owned by another user, uploads fail with EACCES, and /server/health returns 503 with a storage:local error (health results are cached for HEALTHCHECK_CACHE_TTL, five minutes by default, so a fix can take that long to show). Docker Desktop on macOS and Windows usually needs no change.
Connect Your Tools
# App .env (a .env file does not expand variables: write the literal address and token)
DIRECTUS_URL=http://localhost:8055 # the port you put in LOCAL_DIRECTUS_PORT
DIRECTUS_TOKEN=<value of LOCAL_DIRECTUS_ADMIN_TOKEN> # local dev only
- SDK. See the
sdk-patternsskill: static token on the server,authentication('json')for a login in Node,authentication('session', { credentials: 'include' })in the browser. - MCP. Enable it once in the Studio under Settings → AI → Model Context Protocol, then register
${DIRECTUS_URL}/mcpwith your client (seemcp-tools). For a local instance a static token is the simplest start. Create a dedicated user with its own policy for AI work rather than reusing the admin account. - Frontend dev server on another origin: set
LOCAL_FRONTEND_ORIGINto it. The origin must be listed inCORS_ORIGINfor both REST and WebSockets.
Daily Commands
docker compose logs -f directus # follow logs
docker compose restart directus # after changing .env or extensions
docker compose down # stop, keep data
To start over, stop the stack and delete the data/ and uploads/ directories. The next up bootstraps a fresh database and recreates the admin from .env.
Moving a Schema Between Instances
Snapshot the local schema, diff it against another instance and apply (admin token, see api-reference for the pipeline):
curl -s -H "Authorization: Bearer ${LOCAL_DIRECTUS_ADMIN_TOKEN}" \
"http://localhost:${LOCAL_DIRECTUS_PORT:-8055}/schema/snapshot" > schema-snapshot.json
Snapshots are capped by IMPORT_MAX_FILE_SIZE (default 50mb) when uploaded to /schema/diff or /schema/apply.
Extensions
Mount extensions into ./extensions and keep EXTENSIONS_AUTO_RELOAD: "true" for local development. The published Directus 12 images are hardened: npm and npx are removed from the runtime, and the -dhi variant (for example directus/directus:12.4.1-dhi) is distroless with no shell at all. So you cannot install extensions or run npx directus ... inside the container.
- Build outside, copy in. Install and build the extension on your machine or in a build stage, then mount the finished directory (it needs a
package.jsonand adist/folder) intoextensions/. - Bake into an image with a multi-stage Dockerfile and copy with
--chown=node:node:
FROM node:22-alpine AS build
WORKDIR /extension-build
RUN corepack enable && pnpm init && pnpm add <extension-package>
FROM directus/directus:12.4.1
COPY --from=build --chown=node:node /extension-build/node_modules/<extension-package> /directus/extensions/<extension-name>
Keep the Alpine version of the build stage in line with the Directus image when an extension has native dependencies. The -dhi image has no wget, so the compose health check above does not work with it: probe /server/ping from outside the container instead.
- Directus CLI is still there, call it with
node:
docker compose exec directus node /directus/cli.js database migrate:latest
Upgrading
- Read the breaking changes for every version you skip (Directus docs, Releases, Breaking changes). Directus 12 notes:
/server/healthneeds a token,IP_TRUST_PROXYdefaults tofalse, the Studio shows published items of versioned collections read-only, update and delete flow operations without a target returnnull. 12.4.0 has a bug readingdirectus_foldersas a non-admin, so go to 12.4.1 or later. - Back up first:
docker compose exec database pg_dump --username=directus directus > backup.sql, plus theuploads/directory. - Change
LOCAL_DIRECTUS_VERSIONin.env, thendocker compose pull directus && docker compose up -d. Migrations run automatically on start. - Check
docker compose logs directusand/server/ping.
To go back to an older version, restore the backup taken before the upgrade. Changing the image tag back alone leaves a database that was already migrated by the newer version.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
required variable ... is missing a value |
A ${VAR:?...} guard fired. Set the variable in .env |
A value in the running container is not the one in .env |
A variable with the same name is exported in your shell and wins over .env. Unset it, or run docker compose from a clean environment with env -i PATH="$PATH" HOME="$HOME" docker compose up -d |
| Port already in use | Another process owns the host port. Set LOCAL_DIRECTUS_PORT to a free one and update PUBLIC_URL consumers |
| Directus restarts in a loop, logs show database connection errors | Wrong LOCAL_DB_PASSWORD. The database directory keeps the first password: delete data/database to re-initialize, or change the password inside PostgreSQL |
| Login works, but the browser app gets CORS errors | LOCAL_FRONTEND_ORIGIN does not match the app origin exactly (scheme, host and port) |
503 from /server/health with a storage:local error, uploads fail with EACCES |
uploads/ is not writable for uid 1000, see the chown in Start and Verify |
403 from /server/health |
Expected without a token in Directus 12. Use /server/ping |
| Cannot sign in with SSO | Directus 12 needs a licensed tier for SSO. Use an email/password user locally |
Assets return 403 for anonymous requests |
Files are private by default. Grant the Public policy read on directus_files, or serve them through a server route that adds the token. Never put ?access_token= in a URL a browser sees (see troubleshoot) |