Add hardened images section to deployments page

content/self-hosting/5.including-extensions.md

@@ -12,7 +12,11 @@ By default, App extensions and API using our [Sandbox SDK](/guides/extensions/ap
 
 ## npm Packages
 
-To install extensions, you will need to build a custom image of Directus. 
+To install extensions, you will need to build a custom image of Directus.
+
+::callout{icon="i-lucide-book-open" color="primary" to="/self-hosting/hardened-images"}
+For the distroless `-dhi` image or running the Directus CLI on a hardened image, see [Hardened Images](/self-hosting/hardened-images).
+::
 
 ### 1. Modify Docker Compose File
 
@@ -25,19 +29,25 @@ build:
 
 ### 2. Create a Dockerfile
 
-At the root of your project, create a file called `Dockerfile`, if one doesn't already exist, and add the following:
+At the root of your project, create a file called `Dockerfile`, if one doesn't already exist. The Directus image doesn't include `npm`, `npx`, or Corepack, so install the extension in a separate build stage and copy the result into the final image:
 
 ```dockerfile
-FROM directus/directus:latest
+# Build stage - a Node.js Alpine image with npm and Corepack
+FROM node:22-alpine AS build
 
-USER root
 RUN corepack enable
-USER node
 
-RUN pnpm install @directus-labs/spreadsheet-layout
+WORKDIR /extension-build
+RUN pnpm init
+RUN pnpm add @directus-labs/spreadsheet-layout
+
+# Final stage
+FROM directus/directus:latest
+
+COPY --from=build /extension-build/node_modules/@directus-labs/spreadsheet-layout /directus/extensions/spreadsheet-layout
 ```
 
-This is an example `Dockerfile` that installs the Spreadsheet Layout via npm. You can change the `RUN pnpm install` line to install any extension published on npm, and add multiple lines for each extension you want to install.
+This example installs the Spreadsheet Layout. Change the `pnpm add` line to install any extension published on npm, and add a `COPY` line for each one.
 
 ### 3. Build Docker Image
 

content/self-hosting/6.hardened-images.md

@@ -0,0 +1,113 @@
+---
+stableId: afb60369-abe7-4b0c-86bb-a36ccf65e4d3
+title: Hardened Images
+description: Understand Directus's hardened and distroless Docker images, and how to install extensions and run the CLI with them.
+---
+
+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](/self-hosting/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](https://docs.docker.com/build/building/multi-stage/) 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:
+
+```dockerfile
+# 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
+```
+
+::callout{icon="i-lucide-triangle-alert" color="warning"}
+**Match the Alpine version across stages**
+Keep the Alpine version of your `node:*-alpine` build stage in sync with the version the runtime image is built on. An extension with native dependencies must be built for the same OS, libc, and runtime environment as the final image, or it can fail to load at runtime. Prefer pure JavaScript extensions where possible. Check the [Directus Dockerfile](https://github.com/directus/directus/blob/main/Dockerfile) for the version currently in use.
+::
+
+The `COPY --from=build` instruction carries the built extension into the [extensions directory](/self-hosting/including-extensions), 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](/self-hosting/including-extensions).
+
+## Database Migrations and Running the Directus CLI
+
+Directus applies migrations automatically on startup, exactly as it did with the previously 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`:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+# 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.