[jahirvidrio]

Description

Both examples under Smaller images without npm/yarn copy only the node binary into a bare alpine / debian:trixie-slim stage, so every runtime library of the official images has to be reinstalled by hand. libatomic was missing from both.

Also moves the builder stages to node:26-* and Alpine 3.24, and uses the same dependency order in both examples.

Motivation and Context

Following the guide produces an image that builds and then fails to start node. Since Node.js 25 the official Linux binaries link libatomic, which Dockerfile-alpine.template installs since #2621 and Dockerfile-slim.template has installed for longer.

Testing Details

readelf -d on the node binary copied out of each builder image (v26.13.0):

Builder	Arch	libatomic.so.1
node:26-alpine3.24	amd64	yes
node:26-alpine3.24	arm64	no
node:26-trixie-slim	amd64	yes
node:26-trixie-slim	arm64	yes

Only x64 uses the official musl tarball, other architectures are still built from source, so the Alpine example breaks on amd64 only. Verified it starts on arm64 with libstdc++ alone.

npm run format:toc:check, format:prettier:check and format:javascript:check pass.

Example Output

/usr/local/bin/node: error while loading shared libraries: libatomic.so.1: cannot open shared object file: No such file or directory

Types of changes

• Documentation

Checklist

• My code follows the code style of this project.
• I have read the CONTRIBUTING.md document.
• All new and existing tests passed.

[MikeMcC399]

Suggested change

	ARG ALPINE_VERSION=3.23
	ARG ALPINE_VERSION=3.24

This should also be updated, as Alpine Linux 3.25 is expected soon, and then Alpine Linux 3.23 will be dropped from Node.js Docker builds.

[MikeMcC399]

Suggested change

	# Add required binaries; libstdc++ and libatomic are runtime dependencies of the
	# official musl build of Node.js
	# Add required binaries

Keep the comments simple, otherwise you have to start to explain that libatomic is only required for Node.js >=25.

[MikeMcC399]

Suggested change

	# Add required binaries; libatomic1 is a runtime dependency of the official
	# Linux builds of Node.js
	RUN apt-get update && apt-get install -y --no-install-recommends dumb-init libatomic1 \
	# Add required binaries
	RUN apt-get update && apt-get install -y --no-install-recommends libatomic1 dumb-init \

Keep comments simple and use the same order of dependencies as for Alpine.

[MikeMcC399]

Please review and make the suggested changes

[MikeMcC399]

On arm64 the musl binary does not link libatomic, so the Alpine example only fails on x64.

That is not a correct conclusion. If you test an update to Node.js 26 on Alpine you find it also fails on amd64. This is because alpine amd64 images are built from source using the official x64 Node.js musl binary.

[jahirvidrio]

Thanks, my explanation was wrong (the description is updated).

Only x64 downloads the official musl tarball, the other architectures are built from source, and the aarch64 build has no libatomic in DT_NEEDED. That is why the Alpine example breaks on amd64 and still starts on arm64 with only libstdc++. debian:trixie-slim needs libatomic1 on both.

All three suggestions are applied in 10d7f3f.

[MikeMcC399]

Thank you for your contribution and for making the changes.
It looks good now. I also ran the examples in my own fork to confirm.