Every line is built on Alpine and on Debian (debian:trixie-slim). The Alpine images own the unsuffixed tags, as before, and also carry an -alpine suffix; the Debian images only carry a -debian suffix. latest becomes the bare variant name and latest-<variant>:
| Alpine | Debian |
|---|---|
26, 26-alpine |
26-debian |
26.13, 26.13-alpine |
26.13-debian |
26.13.1, 26.13.1-alpine |
26.13.1-debian |
latest, alpine, latest-alpine |
debian, latest-debian |
lts, lts-alpine |
lts-debian |
Every numeric directory is a line named after its node major version, with a Dockerfile.alpine and a Dockerfile.debian sharing the line's build context. A build target is <line>-<variant>. configuration/ pins the node release and pnpm major per line, the upstream node:<version>-slim and node:<version>-alpine digests per target, and the Debian and Alpine base images; aliases.json maps latest and lts onto a line.
Build, load and smoke test node 22 for the local platform:
go run ./scripts build 22
go run ./scripts build 22-debianA bare line builds the Alpine variant. The images are tagged as listed under Variants (ghcr.io/panascais-docker/node/node:22, 22-alpine, 22-debian and so on, plus the Docker Hub and Quay names) in the local image store. ./scripts/build-all-parallel.sh [target...] builds every target at once and logs each build to $TMPDIR/node-builds.
Refresh the pins from nodejs.org and Docker Hub:
go run ./scripts updateOn GitHub Actions, plan compares each target's fingerprint with the annotation on the published image, build pushes the stale targets by digest per architecture and publish tags them as multi-platform images.
Every job pulls Docker Hub images, BuildKit included, through mirror.gcr.io to stay clear of Docker Hub rate limits, and falls back to Docker Hub only when the mirror has not cached an image yet.
BuildKit cache mounts reuse downloaded packages between builds.
Both stages of Dockerfile.debian run on DEBIAN_IMAGE and mount /var/cache/apt and /var/lib/apt/lists. The builder copies /usr/local out of the upstream node:<version>-slim image instead of building on it, so old lines whose upstream Debian release has been archived still install packages from current trixie. The packager moves Debian's docker-clean apt hook aside only for its install, so images built on top keep the stock apt behavior:
RUN --mount=type=cache,id=node-apt-cache-${TARGETARCH},sharing=locked,target=/var/cache/apt \
--mount=type=cache,id=node-apt-lists-${TARGETARCH},sharing=locked,target=/var/lib/apt/lists \
mv /etc/apt/apt.conf.d/docker-clean /etc/apt/docker-clean \
&& apt-get update \
&& apt-get install -y --no-install-recommends \
...
&& mv /etc/apt/docker-clean /etc/apt/apt.conf.d/docker-clean \Only the packager stage (ALPINE_IMAGE) of Dockerfile.alpine uses them:
RUN --mount=type=cache,id=node-apk-${TARGETARCH},sharing=locked,target=/apk/cache \
apk update --cache-dir /apk/cache \
&& apk add --cache-dir /apk/cache --cache-predownload \
...The builder stage runs on upstream node:X-alpine, which may ship apk-tools 2.x (Alpine 3.22 or older). Flags like --cache-predownload are apk-tools 3.x only, so the builder installs its two build deps with plain apk add --no-cache binutils curl instead.
Alpine 3.23 ships apk-tools 3.x, where --update / -U means --cache-max-age 0 (always refetch). Do not use it with cache mounts on the packager stage.
Cache IDs of both variants include ${TARGETARCH} so amd64 and arm64 packages do not mix during multi-platform builds. sharing=locked avoids races when matrix jobs build in parallel.
Node 18+ images ship pnpm 12 via get.pnpm.io into /usr/local/bin/pnpm on both variants. All Node 18+ images set PNPM_HOME to /root/.local/share/pnpm and a PATH that prefers /usr/local/bin while including /root/.local/share/pnpm/bin, so the standalone CLI is not affected by store mounts in downstream builds.
This image does not cache-mount pnpm during its own build — it only downloads the standalone CLI (~few MB), so a store cache would add complexity for little gain.
Application Dockerfiles should cache installs at a separate path such as /pnpm/store, not /root/.local/share/pnpm/store. See pnpm Docker docs.
All Node 18+ images ship enableGlobalVirtualStore: false in /root/.config/pnpm/config.yaml so global installs (pnpm add -g) work with BuildKit cache mounts on the store path (see downstream ci-node).
- Silas Rech (silas@panascais.net)
- Maximilian Schagginger (max@panascais.net)
Interested in contributing to Node? Contributions are welcome, and are accepted via pull requests. Please review these guidelines before submitting any pull requests.