Hardened Images

Directus publishes Docker images hardened for production: the standard directus/directus image and a distroless Docker Hardened Image (DHI) variant tagged with a -dhi suffix. This page explains what they do and how to run Directus with them.

What is a Hardened Image?

A hardened image is a container image that has been stripped down and locked down to reduce its attack surface. It includes only what the application needs to run, so there are fewer components an attacker could use to move around inside a compromised container.

Directus hardens its images at two levels:

• The standard directus/directus image applies OS-level patches at build time and removes npm and npx from the runtime. It still includes a shell, so you can open an interactive shell inside the container.
• The -dhi variant is a Docker Hardened Image built on a distroless base. On top of the standard image's hardening, it removes the shell, package manager, and other general-purpose utilities entirely.

These images offer:

• A smaller attack surface - removing npm, npx, shells, and other binaries means there are fewer components to exploit.
• Fewer vulnerabilities - a minimal set of packages results in fewer reported CVEs to track and patch.
• A non-root runtime - the container runs as an unprivileged user by default.
• A smaller image size - fewer packages means faster pulls and less to store.

These same properties introduce constraints. Because neither image ships npm or npx, you cannot install extensions at runtime on either one. The -dhi variant has no shell at all, so you also cannot open an interactive shell inside it. Any customization, such as including extensions, must be done at build time.

Running npm and npx Commands with a Multi-Stage Build

Since neither image ships npm or npx, use a multi-stage Dockerfile to install extensions or run other build-time commands. Run those commands in an earlier stage based on a node:*-alpine image, then copy only the resulting files into a final stage based on the hardened image. The build tooling never becomes part of the image you ship.

This is the recommended approach when you need to:

• Install extensions from npm.
• Build local extensions or compile other assets.
• Run any other tooling that relies on npm or npx.

Example Dockerfile

The following Dockerfile installs an extension in a node:*-alpine build stage, then copies it into a hardened final stage:

# Build stage
FROM node:{version}-alpine AS build

RUN corepack enable

WORKDIR /extension-build
RUN pnpm init
RUN pnpm add @directus-labs/spreadsheet-layout

# Final stage - the hardened image
FROM directus/directus:{version}-dhi

COPY --from=build --chown=node:node /extension-build/node_modules/@directus-labs/spreadsheet-layout /directus/extensions/spreadsheet-layout

The COPY --from=build instruction carries the built extension into the extensions directory, where Directus loads it on startup. Only the final stage is published, so the build tooling never ends up in your runtime.

Directus images run as the unprivileged node user rather than root, so files copied from a build stage must be readable by that user. Always include --chown=node:node when copying extensions or other files into the final stage.

This example ships the distroless -dhi image. Drop the -dhi suffix to build on the standard image instead, which is still hardened but not distroless - the process is identical.

Add a COPY line for each extension you install. Each copied extension should be a directory containing a package.json file and a dist directory, matching the structure Directus expects in the extensions directory.

Pin the final stage to a specific Directus version rather than using the latest tag, so upgrades are deliberate and builds are reproducible. For the same reason, commit your lockfile and use a frozen install in your build (for example, pnpm install --frozen-lockfile) instead of resolving dependency versions at build time. Build the image with docker compose build and start it with docker compose up as normal, following the same steps described in Including Extensions.

Database Migrations and Running the Directus CLI

Directus applies migrations automatically on startup, exactly as it does with the non-hardened images, and you can also run them manually against a running container with the Directus CLI.

Normally you run the Directus CLI through npx directus <command>, but neither image ships npx. The CLI itself is still present in the container, so you can call it directly with node, pointing at the CLI entrypoint at /directus/cli.js:

docker compose exec directus node /directus/cli.js <command>

This runs against a container that is already up, so use it for one-off tasks against a running deployment. For example, to apply the latest database migrations:

docker compose exec directus node /directus/cli.js database migrate:latest

Any command you would normally pass to the Directus CLI works the same way:

# Bootstrap the project (run migrations and create the initial admin user)
docker compose exec directus node /directus/cli.js bootstrap

# Roll the database back one migration
docker compose exec directus node /directus/cli.js database migrate:down

# Reset a user's password
docker compose exec directus node /directus/cli.js users passwd --email admin@example.com --password new-password

Extension Development

Local extension development is unchanged by the hardened images. You can develop against a local Directus instance or build an extension locally and mount it into the container, just as before. Runtime features such as EXTENSIONS_AUTO_RELOAD continue to work, since they rely only on Node.js. The build-time constraints on this page apply to installing extensions into the image, not to developing them.

Debugging

Because the -dhi image has no shell, you cannot open an interactive session inside the container with commands like docker exec -it directus sh. This is by design - hardened containers are intended to run their entrypoint and nothing else, rather than be treated like a virtual machine.

To troubleshoot a hardened deployment, rely on:

• Container logs via docker compose logs directus.
• Docker-provided tooling such as docker stats for resource usage and health checks for liveness.
• The Directus CLI through node /directus/cli.js as shown above, for one-off administrative tasks.