Repository navigation
Add note to DockerHub indicating Alpine images rely on experimental and unofficial-builds #2011
Description
Activity
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.Reacted by Beth GriggsYeah, I agree we should do that 👍 Suggestions on the wording is very welcome! 😀 I'm bad at those sorts of things
Regarding verbiage something akin to:
The binaries built into these images are not signed by the Node.js release team
Reacted by Peter Dave HelloWhat 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@PeterDaveHello's suggestion seems reasonable to add. Who has permission to update this? (cc: @mhdawson who may know)
I can help submit the PR for the GitHub README, but I don't have permission to make changes on Docker Hub.
Reacted by Beth GriggsFrom https://hub.docker.com/_/node:
- Source of this description:
docs repo'snode/directory (history)
(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)- Source of this description:
Looks like its been figure out and is progressing. Let me know if you need my help.
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-alpine -
Similarly 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=10782897
-
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?)
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":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 runningapk 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":
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.
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 runningapk 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++).
- linux-x64-musl: Linux x64 binaries compiled against musl libc. Primarily useful for users of Alpine Linux. These Node.js builds require the
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.
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.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/muslremains "Experimental" at this time.
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/.