Repository navigation
Add note to DockerHub indicating Alpine images rely on experimental and unofficial-builds #2011
Description
A 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/.
Activity
yosifkit commentedon Dec 18, 2023
I'd guess that adjusting the
node:<version>-alpinesection would be a useful place to put it. This is generated from a generic template, but can be overridden like we do ingolangwith avariant-alpine.md.SimenB commentedon 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 commentedon Dec 19, 2023
Regarding verbiage something akin to:
PeterDaveHello commentedon Mar 29, 2024
What about this:
We could also add:
BethGriggs commentedon Aug 12, 2024
@PeterDaveHello's suggestion seems reasonable to add. Who has permission to update this? (cc: @mhdawson who may know)
PeterDaveHello commentedon 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 commentedon Aug 12, 2024
From https://hub.docker.com/_/node:
(specifically, what I'd recommend is a custom
variant-alpine.mdlike the one Go has: https://github.com/docker-library/docs/blob/ab0984534328ccfd0128d79fcfe6eff6f8600e4c/golang/variant-alpine.md vs the stock copy at https://github.com/docker-library/docs/blob/ab0984534328ccfd0128d79fcfe6eff6f8600e4c/.template-helpers/variant-alpine.md)mhdawson commentedon Aug 20, 2024
Looks like its been figure out and is progressing. Let me know if you need my help.
LaurentGoderre commentedon Aug 26, 2024
docker-library/docs#2484
MikeMcC399 commentedon Jan 28, 2026
This issue has stalled (thanks to @sxa for mentioning it!)
In https://github.com/nodejs/docker-node/blob/main/README.md#nodealpine in this repo there is no mention that the Alpine Docker image is based on a Node.js
muslbuild with experimental status and relies on unofficial builds. Edit: this is now resolved - see https://github.com/nodejs/docker-node/blob/main/README.md#musl-builds-for-alpineSimilarly on https://hub.docker.com/_/node#nodeversion-alpine there is also no warning of the experimental status, although it does mention
musl. It links to an 11 year old discussion thread in https://news.ycombinator.com/item?id=10782897tianon commentedon 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 commentedon Jan 29, 2026
@tianon
I believe the intention of this issue was only to communicate the current upstream status. Although the
muslbased release is Experimental, the https://github.com/nodejs/unofficial-builds/ README > Builds section includes the following paragraph which states "support is generally good":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 commentedon Jan 29, 2026
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 commentedon Jan 30, 2026
MikeMcC399 commentedon May 11, 2026
The https://github.com/nodejs/unofficial-builds/ README > Builds section no longer makes any claim that "support is generally good":
MikeMcC399 commentedon May 21, 2026
Support for resolving this issue is now provided by README > musl builds for Alpine which decribes
node:*alpine*images foramd64as "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 commentedon Sep 29, 2026
The BUILDING > Platform list reference document in the Node.js
mainbranch now reflects that Alpine Linux onx64(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.arm64/muslremains "Experimental" at this time.