ci(docker): publish multi-arch Docker images from a manual workflow

[wayfarer3130]

Summary

This PR adds a manual workflow that publishes the Docker image for linux/amd64 and linux/arm64. The PR also merges Dockerfile and arm-Dockerfile into one Dockerfile, and makes the image install its packages from pnpm-lock.yaml. A new CI workflow builds and tests the image for both architectures in a pull request that changes the files of the image.

The publish workflow builds release tags from the publish workflow of #137. The first tag that it can build is the first release after the merge of this PR.

Security fix: the image did not use the lockfile

The old installer stage ran npm install on the packed packages. npm ignored pnpm-lock.yaml and the overrides of pnpm-workspace.yaml, and resolved each dependency again.

• A local build of 1.7.7 with the old Dockerfile held 21 package versions that are not in the lockfile.
• These versions include adm-zip 0.5.17 and 0.5.18, with 5 high advisories (for example GHSA-8238-w5pm-2374). The override pins adm-zip to 0.6.1.
• dcmjs-dimse also brought dcmjs 0.38.3. The override pins dcmjs to 0.52.0.
• npm got @radicalimaging/static-wado-plugins from the registry with the range >=1.7.7. A later build of the same tag could get a newer version.
• The published images up to 1.7.6 come from the same installer stage, so they very probably have the same problem.

The builder now runs pnpm deploy --prod for @radicalimaging/static-wado-webserver. On amd64 and on arm64, the image now holds no package version that is not in pnpm-lock.yaml.

Manual release of 1.7.7

A maintainer built 1.7.7 by hand from this branch (the code of v1.7.7 and the Docker changes of this PR at that time), and pushed it to Docker Hub:

• braveheartsoftware/static-dicomweb:1.7.7 and :latest are one multi-arch index (sha256:c932b0bf9d27…) for linux/amd64 and linux/arm64, with attestations.
• The build of arm64 ran under QEMU on an amd64 host.
• The arm64 image from Docker Hub holds adm-zip 0.6.1.
• That image has the OCI labels of oven/bun (for example org.opencontainers.image.source=https://github.com/oven-sh/bun and version=1.3.13), because the Dockerfile set no labels then. The current Dockerfile sets the labels of this project. The 1.7.7 image keeps the old labels; the next release gets the correct ones.
• GHCR has no image yet. The first run of the workflow creates the GHCR package.

Changes for users

• The images are multi-arch from 1.7.7: one tag (for example 1.7.7 or latest) holds linux/amd64 and linux/arm64, and Docker selects the correct architecture for the host. Before, Docker Hub had amd64 images only. An arm64 image existed only as a local build (pnpm run docker:build:arm), with the local tag :arm.
• The DIMSE SCP is not in the image. The old tag v1 (2024-11-06, amd64) started /app/startStaticDicomweb.sh, which ran dicomwebserver and dicomwebscp scp -p 11115. No image since at least 1.7.6 contains dicomwebscp, and the default command runs only monitordicomwebserver.
  • docker/docker-compose.yml moves from v1 to latest, and drops the mapping of port 11115. A compose user who used the SCP on 11115 loses it.
  • The README no longer maps a DIMSE port in its docker run example, and says that the image has no SCP.
• docker/docker-compose.yml does not force platform: linux/amd64 now, so an arm64 host runs the image without emulation.
• An npm release does not publish an image. A maintainer must start the workflow.
• The workflow makes only the tags X.Y.Z and latest. It makes no X or X.Y tags.
• A version keeps one image. A run for a version that a registry holds with another image fails, unless the maintainer sets overwrite.
• latest moves only forward. A run for a release moves latest when latest holds an older version, also when a newer tag on master has no image yet. A re-run of an older release does not move latest back.
• The images of the workflow carry the OCI labels and index annotations of this project: title, description, url, source, documentation, licenses (MIT), version, revision, and created (the time of the release commit).
• The arm64 image has the same default command as the amd64 image: monitordicomwebserver. The old arm-Dockerfile used dicomwebserver, and had no curl and no EXPOSE 6499.
• The images of releases after 1.7.7 are also on GHCR: ghcr.io/radicalimaging/static-dicomweb.
• /app in the image now holds the deployed static-wado-webserver package (bin/, lib/, dist/, package.json, pnpm-lock.yaml), not an npm project with five file: dependencies and a package-lock.json. The commands createdicomweb, mkdicomweb, dicomwebserver and monitordicomwebserver stay on PATH. node_modules/.bin no longer has the dev tools of the old image (for example acorn, terser, webpack).
• pnpm run docker:build:arm now builds a real linux/arm64 image. On an amd64 host, the build needs QEMU. Before, the script built an image for the architecture of the host.
• The local scripts docker:build, docker:build:arm, docker:run and docker:dicomwebserver now use the local tags static-dicomweb:dev and static-dicomweb:dev-arm64, not braveheartsoftware/static-dicomweb:latest. A local build then cannot replace a release by accident.
• /app/startStaticDicomweb.sh now runs only monitordicomwebserver, and git marks it executable (100755), so an image built on Linux can run it. Before, it also started dicomwebscp, which the image does not contain.

Implementation

Dockerfile

• The builder uses node:24-trixie, and the final stage uses oven/bun:1.3.13. Each image is pinned by digest. Both images use Debian trixie, so the canvas that arm64 compiles finds the same libraries at run time.
• The Dockerfile frontend (docker/dockerfile:1.7-labs) is also pinned by digest.
• The apt packages are not pinned, because Debian removes old versions from trixie, and a pinned version then stops installing. Each apt-get install uses --no-install-recommends, and the final stage installs ca-certificates explicitly.
• The final stage runs apt-get upgrade, because the pinned oven/bun image predates the trixie security updates. docker scout on the amd64 image: before, 5 critical and 15 high findings (perl, glibc, pcre2, sqlite3 and others); after, 0 critical and 3 high. The 3 have no fixed version (zlib, cyrus-sasl2), or are the accepted braces advisory of pnpm-workspace.yaml. The published 1.7.7 image has the old packages.
• canvas 3.1.0 has no linux-arm64 prebuilt binary, so arm64 compiles canvas from source. The builder installs the canvas build packages on arm64 only. node:24-trixie has all of them except libgif-dev, but the list names each one.
• On amd64, canvas uses the prebuilt binary, which bundles its libraries. If the download fails, canvas compiles against the libraries of node:24-trixie, and the final stage does not have them. The final stage runs require('canvas').createCanvas(1, 1), so such an image fails the build, also in a local build.
• The global install of pnpm keeps its install scripts. Without them, pnpm runs its Node launcher, which gives no node-gyp to the canvas build on arm64. A local arm64 build with --ignore-scripts failed with node-gyp: not found. The pnpm version must stay equal to packageManager in package.json; corepack is not an option, because Node removes it after version 24.
• The build uses the filter @radicalimaging/static-wado-webserver..., so the build covers the server and the 5 workspace packages that it needs. These are the packages that pnpm deploy copies.
• The final stage links dicomwebserver and monitordicomwebserver into node_modules/.bin, because pnpm deploy links only the commands of the dependencies.
• The final stage replaces the OCI labels of oven/bun. The build arguments IMAGE_VERSION, IMAGE_REVISION and IMAGE_CREATED set the release values; a local build gets dev, unknown and unknown.
• .dockerignore excludes the testdata submodule. The docker:build scripts no longer run cleanTgz.

Workflow .github/workflows/docker-publish.yml

• workflow_dispatch is the only trigger. The inputs:
  • tag: optional. An empty value selects the newest vX.Y.Z tag on master.
  • ghcr_only: skip Docker Hub.
  • overwrite: replace the image of a version in both registries. The resolve job refuses overwrite together with ghcr_only, because that run gives the two registries two images for one version.
• A run that does not start on master fails. It does not show a green run that publishes nothing.
• The resolve job runs scripts/release/docker-release.mjs:
  • The script uses only the release tags that master contains.
  • The tag must carry its version in packages/create-dicomweb/package.json.
  • The Dockerfile of the tag must have a RUN line with pnpm … deploy --prod. The script refuses v1.7.7 and older tags with a clear error, so a run cannot build the old Dockerfile.
  • The error messages quote the input in JSON, so a newline in the input cannot start a workflow command.
• The build job checks out the commit SHA from resolve, and builds on a native runner (ubuntu-24.04 and ubuntu-24.04-arm).
  • The BuildKit daemon (moby/buildkit:v0.34.0) is pinned by digest, because it runs the build and holds the push credential.
  • Each build pushes an untagged image by digest to GHCR with GITHUB_TOKEN, with SBOM and provenance attestations. The label created is the time of the release commit. A rebuild gives the same label, but after apt-get upgrade it can hold newer packages.
  • Each build then runs scripts/docker-smoke-test.sh. canvas must make a PNG, createdicomweb --help and mkdicomweb --help must succeed, the other commands must exist, and the default command must answer GET /dicomweb/studies within 180 seconds (an arm64 image under QEMU starts slowly). Each request has a limit of 5 seconds. SMOKE_TIMEOUT_SECONDS raises the wait for a local QEMU run; under QEMU the monitor of the image can restart the slow server first. A failed test stops the run before the approval, so a broken image gets no tag.
• The publish job uses the docker-hub environment, on the pinned runner ubuntu-24.04, with contents: read and packages: write. The run stops at this job until a reviewer approves the deployment.
  • Only this job can read DOCKERHUB_TOKEN. When the secret is not set and ghcr_only is not set, the job fails. Only a job of the environment can see the secret, so this check runs after the approval.
  • The job checks out scripts/docker-publish-tags.sh from master (the dispatch ref) and runs it. The job runs no other code of the repository, and no BuildKit daemon.
• scripts/docker-publish-tags.sh writes the tags:
  • When GHCR holds the version already (a run that stopped before Docker Hub, or a ghcr_only run), the script publishes that image and not the new build. The revision label of each platform image must be the release commit, because GHCR is not behind the approval. Otherwise the run fails, unless overwrite is set.
  • A tag that holds the same manifests counts as done, so "Re-run failed jobs" continues. A tag that holds another image stops the run, unless overwrite is set.
  • latest moves only forward: each run moves latest, unless the version label of the current latest is a newer X.Y.Z. The newest tag on master does not decide it, because an npm release does not publish an image, so an older release can still move latest forward. Another label (for example dev of a local build, which sort -V puts above every number) does not hold latest.
  • The script refuses a digest file name that is not 64 hex characters, and uses inherit_errexit, so a failed read inside $(...) stops the script.
  • Only the answer "not found" counts as a free tag. Any other error of the registry stops the run.
  • The script adds the OCI annotations to the index, and then checks that each new tag holds the expected manifests.
  • A manual push between the checks and the write is not detected. Do not push these tags by hand.
• The workflow follows the rules of publish.yml: actions pinned by commit, no build cache, and permissions: {} at the top level. The digest artifacts last 30 days, because an approval can wait 30 days. The repository allows 90 days.

Workflow .github/workflows/docker-ci.yml

• A pull request that changes Dockerfile, .dockerignore, docker/, package.json, tsconfig.json, tsconfig.base.json, babel.config.js, pnpm-lock.yaml, pnpm-workspace.yaml, packages/, the Docker scripts or a Docker workflow starts this workflow. A manual start is also possible.
• The image job builds the image for amd64 and arm64 on native runners without a push, and runs scripts/docker-smoke-test.sh. A broken image then shows up before a release, and not after npm holds the version.
• The publish-tags job runs shellcheck on the Docker scripts, and runs scripts/docker-publish-tags.test.sh against a local registry.

Limits

• The environment gates Docker Hub only. GHCR takes GITHUB_TOKEN, so any workflow of this repository with packages: write can write to the GHCR package, from any branch. The revision check limits what can reach Docker Hub from GHCR, but a forged label can pass it.
• "Prevent self-review" is off, so one maintainer can start a run and approve it.
• Docker Hub cannot limit a personal access token to one repository. The token can write to every repository of braveheartsoftware.
• A failed or rejected run leaves untagged digests in GHCR.
• Docker Hub has OIDC (trusted publishing) for GitHub Actions since July 2026, but only for organization accounts on the Team, Business, DHI or Docker-Sponsored Open Source plans. braveheartsoftware is a personal account. A later move to an organization changes only the Docker Hub login step. Because the publish job names an environment, the OIDC subject is repo:RadicalImaging/Static-DICOMWeb:environment:docker-hub, and the Docker Hub ruleset must match that subject.

Setup before the first run

1. On Docker Hub, sign in as braveheartsoftware. Create a personal access token with the access "Read & Write".
2. On GitHub, create the environment docker-hub. Add a required reviewer, and keep "Prevent self-review" off.
3. In docker-hub, set "Deployment branches and tags" to "Selected branches and tags", with the branch master only.
4. In docker-hub, add the secret DOCKERHUB_TOKEN. The variable DOCKERHUB_USERNAME is optional, and the default is braveheartsoftware.
5. After the first run, open the package static-dicomweb on GitHub, and change the visibility to public. GHCR creates a new package as private. Do not push to GHCR by hand before the first run.

Tests

• release.test.mjs has two new tests, both in the category "the API must do this":

  • chooseRelease: the selection of the newest tag, the numeric order, and the refusal of a tag that is not a release tag.
  • findTagProblems: a wrong version, a missing package.json, a Dockerfile without the lockfile install, and a lockfile install in a comment only.

• scripts/docker-publish-tags.test.sh ("the API must do this") runs the tag script against a local registry on 127.0.0.1, with small FROM scratch images per architecture that carry attestations and labels. It has 18 checks:

  • a ghcr_only publish leaves Docker Hub alone; ghcr_only with overwrite and a bad digest file name are refused;
  • a later full run publishes the GHCR image, so both registries and latest hold one image;
  • a re-run continues;
  • a GHCR version from another commit is refused;
  • Docker Hub with another image is refused, and overwrite replaces it in both registries;
  • a newer release moves latest to that release, and a re-run of an older release leaves latest alone;
  • a dev label on latest does not hold latest.

  Each refusal check also matches the error message. Mutation tests: a copy of the script without the revision check and without the guard of latest fails exactly those two checks, and a copy without the X.Y.Z filter fails exactly the dev check.

• docker-release.mjs on this repository refuses an empty input and v1.7.7 (old Dockerfile), v1.7.6 (master does not contain that tag) and v1.5.0.

• scripts/docker-smoke-test.sh passes on the local images, and fails with exit code 127 on an image without the commands.

• Local builds of this branch for linux/amd64 and linux/arm64 (QEMU) succeed, with the labels of this project. The smoke test passes on amd64, and on arm64 under QEMU with SMOKE_TIMEOUT_SECONDS=600 (302 seconds). In the images of the previous commit, HTTPS works and each package version is in pnpm-lock.yaml.

• actionlint reports no errors for both workflows. shellcheck 0.9.0 (the version of the ubuntu-24.04 runner) and 0.11.0 report no errors for the three Docker scripts and docker/startStaticDicomweb.sh. An earlier commit of this PR failed in CI, because it disabled only SC2329, the newer code of SC2317.

• docker-publish.yml did not run. It runs only from master, and it needs a release tag that contains the new Dockerfile. docker-ci.yml runs in this PR.

🤖 Generated with Claude Code