Distroless images
NodeSource publishes distroless N|Solid Runtime images on Docker Hub. A distroless image contains the N|Solid Runtime and the few system libraries it needs to run, and nothing else: no shell, no package manager, and no npm. This page explains how the images work, how to build an application on them, and how they differ from the regular Debian and Alpine images.
Distroless images are designed to be the final stage of a multi-stage build: you install dependencies and build your application in a regular N|Solid image, then copy the result into the distroless image.
Why use a distroless image
- Smaller attack surface. With no shell, package manager, or core utilities in the image, an attacker who gets code execution in the container has far fewer tools to work with.
- Fewer scanner findings. The image has a small fraction of the operating system packages of a regular Debian image, and no npm or Yarn, so vulnerability scans report less to triage.
- Smaller images. About 210 MB uncompressed (about 75 MB to download), compared with about 530 MB (335 MB to download) for the
trixie-slimimage and about 1.5 GB (690 MB to download) for the fulltrixieimage. - Non-root by default. The
-nonrootvariant runs as an unprivileged user, so it satisfies KubernetesrunAsNonRootpolicies without extra configuration.
The images run the same N|Solid Runtime as the regular images. Metrics, tracing, CPU profiles, heap snapshots, and the other N|Solid Console features work the same way.
Image tags
Two variants are available for each supported Node.js line:
| Variant | Runs as | Base image |
|---|---|---|
trixie-distroless | root | gcr.io/distroless/cc-debian13 |
trixie-distroless-nonroot | UID/GID 65532 (nonroot) | gcr.io/distroless/cc-debian13:nonroot |
| Tag | Example |
|---|---|
<line>-trixie-distroless-latest | lithium-trixie-distroless-latest |
<line>-trixie-distroless-nonroot-latest | krypton-trixie-distroless-nonroot-latest |
<line>-trixie-distroless-<node-version>-ns<nsolid-version> | lithium-trixie-distroless-26.13.1-ns6.3.10 |
<line>-trixie-distroless-nonroot-<node-version>-ns<nsolid-version> | lithium-trixie-distroless-nonroot-26.13.1-ns6.3.10 |
<line> is lithium (Node.js 26), krypton (Node.js 24), or jod (Node.js 22). All distroless images are published for amd64 and arm64.
Distroless images are opt-in. The latest, alpine-latest, and <line>-latest tags keep pointing to the regular images, so existing deployments don't switch to a shell-less image by accident.
Use the -nonroot variant in production unless your application needs root. In production, also pin a specific release instead of a latest tag. See Docker Hub for the full list of tags.
Like the other N|Solid images, the distroless images are signed with Cosign and published with SBOM and build provenance attestations. The base image is pinned by digest and updated with N|Solid releases.
Build an image for your application
Use a regular N|Solid image of the same Node.js line as the build stage, and the distroless image as the runtime stage. This example Dockerfile assumes your application starts with node server.js and listens on port 3000:
# Build stage: has a shell, npm, and build tools
FROM nodesource/nsolid:lithium-trixie-slim-latest AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
# Runtime stage: the N|Solid Runtime and your application
FROM nodesource/nsolid:lithium-trixie-distroless-nonroot-latest
COPY /app /app
WORKDIR /app
ENV NODE_ENV=production
EXPOSE 3000
CMD ["server.js"]
COPY --from=build keeps the owners the files had in the build stage. Here that's root, and the files are readable by everyone, which is all the application needs to run. Don't make the user the application runs as the owner of its own code: if the application is compromised, an attacker could then rewrite it. For the same reason, set WORKDIR after the COPY. In the -nonroot image, a WORKDIR that creates the directory makes it owned by UID 65532, which lets the application add, replace, or delete files in it.
If your application writes to a directory, such as an upload or cache directory, create it in the build stage and give only that directory to UID 65532:
# In the build stage
RUN mkdir -p /app/uploads && chown 65532:65532 /app/uploads
Other writes can go to /tmp or /home/nonroot.
The image's entrypoint is the nsolid binary, so CMD contains only the arguments for N|Solid: the path to your entry file, plus any Node.js flags you need, for example CMD ["--enable-source-maps", "server.js"].
Build it:
docker build -t my-app .
Connect to the N|Solid Console
Connecting to the N|Solid Console only needs environment variables and outbound network access, so it works the same way as with the regular images. Set NSOLID_SAAS to connect to N|Solid SaaS, or NSOLID_COMMAND for a self-hosted N|Solid Console. For all options, see Runtime configuration.
Treat your N|Solid SaaS token as a secret. Store it in a secrets manager or vault, and don't bake it into your image.
Run the image you built:
docker run --rm -p 3000:3000 \
-e NSOLID_APPNAME="my-app" \
-e NSOLID_TAGS="production,nsolid-lithium" \
-e NSOLID_TRACING_ENABLED=1 \
-e NSOLID_SAAS="$NSOLID_SAAS" \
my-app
You can also run a script directly from the published image by mounting it. No --entrypoint override is needed:
docker run --rm \
-e NSOLID_APPNAME="my-app" \
-e NSOLID_SAAS="$NSOLID_SAAS" \
-v "$PWD:/app:ro" \
nodesource/nsolid:lithium-trixie-distroless-nonroot-latest /app/index.js
Deploy on Kubernetes
You can start from the Kubernetes example on the Docker page, but change its pod securityContext. That example sets runAsUser: 1016, the nsolid user that only exists in the regular images.
The -nonroot variant's user is the numeric UID 65532, so runAsNonRoot: true passes without runAsUser. Set fsGroup: 65532 so that mounted volumes are writable by that user:
spec:
securityContext:
runAsNonRoot: true
runAsUser: 65532
runAsGroup: 65532
fsGroup: 65532
The trixie-distroless variant runs as root, so remove runAsNonRoot and runAsUser from the securityContext. With runAsNonRoot: true and no runAsUser, Kubernetes refuses to start a container whose image runs as root.
Use httpGet (or tcpSocket) liveness and readiness probes. Probes that run a command in the container, such as exec with curl or sh, don't work because those programs aren't in the image.
Differences from the regular images
Regular Debian images (trixie, trixie-slim, bookworm, bookworm-slim) | Distroless images (trixie-distroless, trixie-distroless-nonroot) | |
|---|---|---|
Shell (sh, bash) | Yes | No |
Package manager (apt) | Yes | No |
| npm, npx, corepack, Yarn | Yes | No |
Node.js headers (for node-gyp) | Yes | No |
Debugging tools (curl, ps, top) | Some | No |
| CA certificates and time zone data | Yes | Yes |
| Entrypoint | docker-entrypoint.sh, CMD ["nsolid"] | nsolid, no default CMD |
docker run <image> server.js | Runs nsolid server.js | Runs nsolid server.js |
docker run <image> bash (or any other command) | Runs that command | Passes bash to nsolid as a script name, and fails |
| Default user | root (the image also includes node, UID 1015, and nsolid, UID 1016) | root, or UID 65532 for -nonroot |
| Default working directory | /tmp | /, or /home/nonroot for -nonroot |
| Platforms | amd64, arm64 | amd64, arm64 |
Limitations
Building your image
- No npm or Yarn.
npm ci,npm start, andnpm runaren't available in the distroless image. Install dependencies in the build stage, and start the application by passing its entry file to N|Solid (CMD ["server.js"]) instead ofnpm start. - No
RUNinstructions. There's no shell, so instructions likeRUN mkdirorRUN chownfail. Prepare files, directories, and their owners in the build stage, and copy them withCOPY --from=build, which keeps their owners. Give UID65532only the directories the application writes to. - Use a matching build stage. Build in
nodesource/nsolid:<line>-trixie-slim, with the same Node.js line as the distroless image. Both use Debian 13 and the same glibc. Don't copynode_modulesfrom an Alpine (musl) or Bookworm build stage: native add-ons compiled there may fail to load. - Native add-ons that need extra system libraries fail to load. Add-ons that dynamically link to libraries such as
libpq,libvips,cairo, orlibjpegfail withcannot open shared object file, because those libraries aren't in the image. Pure JavaScript modules work, and so do add-ons that bundle their own libraries or only need glibc, libstdc++, or OpenSSL. For other add-ons, copy the libraries they need into the image, or use thetrixie-slimimage.
Running and troubleshooting
-
No shell in the container.
docker exec -it <container> shdoesn't work. To inspect a running container, attach an ephemeral debug container that shares its process and network namespaces:# Kubernetes
kubectl debug -it <pod> --image=busybox --target=<container>
# Docker
docker run -it --rm --pid=container:<container> --network=container:<container> busyboxThe N|Solid Console remains the main way to look inside the running process: metrics, CPU profiles, heap snapshots, and traces don't need a shell.
-
Health checks. Prefer your orchestrator's HTTP probes. A Docker
HEALTHCHECKthat runscurlor uses the shell form doesn't work. If you need a DockerHEALTHCHECK, use the exec form with N|Solid itself:HEALTHCHECK CMD ["/usr/local/bin/nsolid", "-e", "fetch('http://127.0.0.1:3000/health').then(r => process.exit(r.ok ? 0 : 1), () => process.exit(1))"]Each check starts a new N|Solid process with the container's
NSOLID_*environment variables, and that process connects to the N|Solid Console. A new short-lived process appears in the Console at every check interval (30 seconds by default) for as long as the container runs. Use HTTP probes when you can. -
Signals and shutdown. N|Solid runs as PID 1, as it does in the regular images. Node.js doesn't install a default
SIGTERMhandler, so an application that doesn't handleSIGTERMis only stopped when the stop timeout expires. HandleSIGTERMandSIGINTin your application, or run the container withdocker run --init. You can't installtiniin the image. -
Permissions in the
-nonrootvariant. The process runs as UID/GID65532and can only write to/home/nonrootand/tmp. Make sure mounted volumes are writable by that user (in Kubernetes, setfsGroup: 65532), and listen on a port above 1024, such as 3000 or 8080. -
The
trixie-distrolessvariant runs as root. Use-nonrootunless your application needs root. -
Base image updates arrive with N|Solid releases. A published tag picks up a newer distroless base image only when a new N|Solid release is built. To get base image security fixes, update to the latest N|Solid release for your Node.js line.
Not available
- Alpine-based or Bookworm-based distroless images.
arm/v7(32-bit ARM) images.debugvariants with a BusyBox shell.
If you need any of these, or a shell inside the container, use the regular Debian or Alpine images.