Skip to content

docs(docker): install libatomic1 in the Node.js runtime stage - #3225

Open
kshanxs wants to merge 1 commit into
voidzero-dev:mainfrom
kshanxs:docs/docker-libatomic
Open

kshanxs wants to merge 1 commit into
voidzero-dev:mainfrom
kshanxs:docs/docker-libatomic

Conversation

@kshanxs

@kshanxs kshanxs commented Oct 24, 2026

Copy link
Copy Markdown
Contributor

Closes #3219

Official Node.js 25+ Linux builds link libatomic (BUILDING.md). Neither debian:bookworm-slim nor gcr.io/distroless/cc ships it, so the Node.js binary copied into the runtime stage fails with libatomic.so.1: cannot open shared object file.

  • SSR Dockerfile: the runtime stage now installs libatomic1. The comment links Node should run on Debian/Ubuntu-based images without having to manually install libatomic first nodejs/node#60790 (still open) and says Node.js 24 and older don't need the step, so readers know why it's there and when they can drop it, as suggested in the issue.
  • Distroless tip: distroless has no package manager, so the tip shows copying libatomic.so.1 from the build stage into /usr/lib/. I kept distroless/cc rather than switching to distroless's Node.js images, since those ship their own Node.js and would lose the exact .node-version match the guide is built around.

Docs only. Verified locally with Docker on linux/amd64, using Node.js 26.12.1 resolved by vp inside ghcr.io/voidzero-dev/vite-plus:latest:

Runtime base Before After
debian:bookworm-slim libatomic.so.1 load error v26.12.1 (also as USER nobody)
gcr.io/distroless/cc-debian12 libatomic.so.1 load error v26.12.1

🤖 Generated with Claude Code

Official Node.js 25+ Linux builds link libatomic, which debian:bookworm-slim
and gcr.io/distroless/cc do not include, so the copied binary fails to start.
Install libatomic1 in the slim runtime stage and show how to copy the
library into a distroless runtime.

Closes voidzero-dev#3219

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docker guide: the runtime stage needs libatomic1 for Node.js 25 and later

1 participant