GeezerVison is showing github.com — Add note to DockerHub indicating Alpine images rely on experimental and unofficial-builds · Issue #2011 · nodejs/docker-node
Add note to DockerHub indicating Alpine images rely on experimental and unofficial-builds #2011DescriptionA somewhat extension to #2000.
I've heard a lot of feedback from users of the Docker Official Node.js Alpine images that they were unaware they rely on experimental status builds (refs: BUILDING.md) from https://unofficial-builds.nodejs.org/. The binaries built into these images are not signed by the Node.js release team which may also be a surprise and/or concern to end users.
I understand the constraints with making those builds an official platform. But, I do think this information is not surfaced well enough today. Users of the pre-built Docker images are unlikely to be looking at the building file in Node.js core repository. It's also easy to see the 'Docker Official' status and assume the contents are as official/supported as the other builds the project provides.
I think we should consider adding a note (or warning?) to the https://hub.docker.com/_/node/ webpage indicating the Alpine Docker images make use of an experimental platform provided by https://unofficial-builds.nodejs.org/. Reacted by Fabian Meyer, Rodney Russ, Michael Dawson, vhscom, Ulises Gascón, Steffen Schroeder, Ivan Velichko and surajtaghash Activityyosifkit commented on Dec 18, 2023 I'd guess that adjusting the node:<version>-alpine section would be a useful place to put it. This is generated from a generic template, but can be overridden like we do in golang with a variant-alpine.md. SimenB commented on Dec 19, 2023 Yeah, I agree we should do that 👍 Suggestions on the wording is very welcome! 😀 I'm bad at those sorts of things vhscom commented on Dec 19, 2023 Regarding verbiage something akin to:
The binaries built into these images are not signed by the Node.js release team
Reacted by Peter Dave Hello PeterDaveHello commented on Mar 29, 2024 What about this:
Notice to Node.js Alpine Docker Image Users
Please be aware that our Node.js Alpine Docker images use builds from https://unofficial-builds.nodejs.org/, which are not signed by the official Node.js release team. These builds are chosen to ensure compatibility and performance within the Alpine environment. We share this information for transparency and to help you make informed decisions regarding your application setup.
We could also add:
For more details and discussion, please refer to: #1025
Reacted by Beth Griggs and Olof Nord BethGriggs commented on Aug 12, 2024 PeterDaveHello commented on Aug 12, 2024 I can help submit the PR for the GitHub README, but I don't have permission to make changes on Docker Hub. tianon commented on Aug 12, 2024 mhdawson commented on Aug 20, 2024 Looks like its been figure out and is progressing. Let me know if you need my help. LaurentGoderre commented on Aug 26, 2024 MikeMcC399 commented on Jan 28, 2026 This issue has stalled (thanks to @sxa for mentioning it!)
tianon commented on Jan 28, 2026 IMO, the fact that it's an unsupported platform in Node.js itself means it should either be supported officially upstream or be removed from the support matrix here (with the caveat that it's popular and seems to work, so perhaps the first option really is a mostly sane one?) MikeMcC399 commented on Jan 29, 2026 @tianon
I believe the intention of this issue was only to communicate the current upstream status. Although the musl based release is Experimental, the https://github.com/nodejs/unofficial-builds/ README > Builds section includes the following paragraph which states "support is generally good":
linux-x64-musl: Linux x64 binaries compiled against musl libc version 1.1.20. Primarily useful for users of Alpine Linux 3.9 and later. Linux x64 with musl is considered "Experimental" by Node.js but the Node.js test infrastructure includes some Alpine test servers so support is generally good. These Node.js builds require the libstdc++ package to be installed on Alpine Linux, which is not installed by default. You can add this by running apk add libstdc++.
Given also that issues on https://github.com/nodejs/unofficial-builds/issues for musl builds have been responded to lately, it doesn't appear to be unsupported, only "Experimental".
Still, there is a fundamental mismatch of publishing experimental components to a site clearly showing the text "Docker Official Image":
 sxa commented on Jan 29, 2026
IMO, the fact that it's an unsupported platform in Node.js itself means it should either be supported officially upstream or be removed from the support matrix here (with the caveat that it's popular and seems to work, so perhaps the first option really is a mostly sane one?)
Hi @tianon yeah I kinda agree with that as a philosophy, and part of me has also been questioning recently if some of these other builds should be pushed as official docker image. (Note: I'm not officially part of Node's docker team at the moment but I have interacted with you on the eclipse-temurin images before) We'd need to find someone willing to step up if we wanted to move it up to an officially supported platform at the Node project, but that would also lead us to look at what others maybe should be moved to a "node-secondary" official repo or similar (I'm guessing that might not be liked by dockerhub) or published as unofficial builds (extra work for the docker-node team) - it's unfortunate that we're currently in a position where we've already pushed some of these as official images since people will see them and assume they're of some level of quality. Do we have easy access to the usage stats on each image currently? I can imagine Alpine/aarch64 could be quite high now too.
Having said that, as @MikeMcC399 states, and backed up by his quotes text, the status of Alpine/x64 is generally good (and Alpine/aarch64 is probably in a decent state too now) and we do test Alpine/x64 in our CI (unlike some of the other builds.
The PR at docker-library/docs#2484 would at least provide a temporary stop-gap until we can determine and implement an approach here.
I would note that there are some other Alpine architectures that we push to official-images, such as s390x, which are even less likely to be actively maintained than Alpine/x64 and so I'd be even more concerned about those. MikeMcC399 commented on Jan 30, 2026 MikeMcC399 commented on May 11, 2026 The https://github.com/nodejs/unofficial-builds/ README > Builds section no longer makes any claim that "support is generally good":
- linux-x64-musl: Linux x64 binaries compiled against musl libc. Primarily useful for users of Alpine Linux. These Node.js builds require the
libstdc++ package to be installed on Alpine Linux, which is not installed by default. You can add this by running apk add libstdc++.
- linux-arm64-musl: Linux arm64 binaries compiled against musl libc. Primarily useful for users of Alpine Linux on arm64 hardware (e.g. Apple Silicon, AWS Graviton). Requires
libstdc++ on Alpine (apk add libstdc++).
MikeMcC399 commented on May 21, 2026 Support for resolving this issue is now provided by README > musl builds for Alpine which decribes node:*alpine* images for amd64 as "Experimental" and other architectures as untested.
In parallel however, nodejs/node#62764 seeks to promote Alpine Linux with musl to Tier 2, and progress is being made in this regard.
The documentation on https://hub.docker.com/_/node#image-variants is in any case outdated, and it remains an open issue to refresh the contents soon. MikeMcC399 commented on Sep 29, 2026 The BUILDING > Platform list reference document in the Node.js main branch now reflects that Alpine Linux on x64 (amd64) is supported with Type 2 support. Routine backporting in Node.js should later show that the supported release lines Node.js 22, 24 & 26 are also covered by the promotion to Tier 2 support.
| Operating System |
Architectures |
Versions |
Support Type |
Notes |
| GNU/Linux |
x64 |
kernel >= 6.12, musl >= 1.2.5 |
Tier 2 |
e.g. Alpine 3.22 |
arm64 / musl remains "Experimental" at this time.
sxa commented on Oct 21, 2026 Noting as an explicit follow up to Mike's comment above that since we publish Alpine/arm64 containers this issue is still valid despite the promotion of Alpine/x64 to tier 2. As far as I'm aware that is the only remaining platform which is not tier 2 but which we still publish to dockerhub.
MetadataMetadataDevelopmentNo branches or pull requestsIssue actions
|
