Document and implement strategy when musl releases (for Alpine) are missing

Situation

Missing / delayed musl builds from https://unofficial-builds.nodejs.org/download/release/, required to build Node.js Docker images for Alpine Linux releases, are causing delays in the release of Debian-based Node.js Docker images.

Refs:
#2355
#2343
#2330

Background

https://github.com/nodejs/node/blob/main/BUILDING.md#strategy states:

There are three support tiers:

Tier 1: These platforms represent the majority of Node.js users. The
Node.js Build Working Group maintains infrastructure for full test coverage.
Test failures on tier 1 platforms will block releases.
Tier 2: These platforms represent smaller segments of the Node.js user
base. The Node.js Build Working Group maintains infrastructure for full test
coverage. Test failures on tier 2 platforms will block releases.
Infrastructure issues may delay the release of binaries for these platforms.
Experimental: May not compile or test suite may not pass. The core team
does not create releases for these platforms. Test failures on experimental
platforms do not block releases. Contributions to improve support for these
platforms are welcome.

Since musl builds belong to the Experimental category, the statement "Test failures on experimental platforms do not block releases." applies to the corresponding upstream Node.js release.

https://github.com/nodejs/unofficial-builds also states:

This project is experimental: its output is not guaranteed to remain consistent and its existence is not guaranteed into the future.

Suggestion

Based on the above, the release of Tier 1 Node.js Debian-based Docker images should not depend on the availability of Experimental Node.js musl releases.

Document the strategy for handling delayed upstream Node.js releases that are missing platforms in the Experimental category:

For instance, add one of the following statement to the README:

Non-availability of Experimental Node.js musl releases does not block the release of Debian-based Node.js Docker images

or generically:

Non-availability of Node.js releases for Experimental platforms defined in the Node.js platform list does not block the release of Docker images based on Tier 1 or 2 Node.js Docker platforms.

This would apply to both security and non-security releases.
Implement the strategy
The following are PR proposals for handling security releases only:
- Evaluate musl build availability for security releases separately for each release line #2348
- Decouple security releases from MUSL builds #2353

We have recently had the situation where other builders of Debian Docker images based on Node.js published a day earlier compared to the main images from this repo.

Image	Published
`node:24.13.0-trixie`	Jan 14, 2026 11:43 pm
`cimg/node:24.13.0`	Jan 13, 2026 8:29 pm
`cypress/base:24.13.0`	Jan 13, 2026 5:10 pm

It would be good for this situation to be avoided in the future, by decoupling Debian releases from Alpine releases.

See also #2011 concerning adding a note about the experimental basis for Alpine releases, which has been out there since 2023 and is still open.

I'm going to copy some of my thoughts from the associated PR into here:

We should understand the history behind the decision to publish our experimental/unofficial Alpine builds up as "official images" on dockerhub and determine if that is a policy we wish to continue. I see three options (although I also accept that there may be people depending on these images in the current location who would be impacted by such as change):
- Stop publishing container images for non-mainstream (i.e. release blocking) platforms
- Separate experimental platforms such as Alpine into a separate official images repository such as "node-experimental" so they are fully decoupled.
- Build the images ourselves and push them up to dockerhub in a separate non-official repository on dockerhub (and/or elsewhere if desired!)
Should we have an option in the node build to allow a build-time message that can be included in the repl startup message so we can make it more visible that these are "unofficial" (from a node perspective) or "experimental" builds?
I don't know if it's a concern but since we also have other Alpine builds which are not even experimental should be really be publishing them at all? I believe Alpine/x64 is the only experimental platform that we have PR testing for so we have a reasonable confidence that it should work, but that is not the case for any of the others, so at the moment we could presumably publish something that crashes on startup.
As mentioned in by Mike in this comment the Alpine size is smaller but is it significant enough that people would choose to use it over Alpine? Do we have usage/download stats from dockerhub available?
As an absolute minimum we should have a note to give users some indication that they may not be good enough for production use. Add unofficial build notice for Node Alpine docker-library/docs#2484 seems to have stalled with no updates since October 2024.
We should also define an addition/removal policy as per Clarify Alpine version support policy #2072 for Alpine versions generally.

As I'm not currently a collaborator (If someone wishes to add me, please do) I do not have permission to add the label to make this as a WG agenda item (See also the issue on when such things are discussed). Also just to add in another related link it looks like there are other concerns that have been raised on the vibrance of this WG to the TSC recently. I also note that I don't think any of the WG members have so far contributed to #2355 which has been open for over two weeks.

Noting that the initial Alpine support was added under #156

@PeterDaveHello

@PeterDaveHello @SimenB As the currently active collaborators in the project do you have any thoughts on any of the above discussion? I personally would not be averse to stopping the publication of Alpine official images unless someone steps up to make it an official platform in the Node.js project (Noting that this echoes one of the comments made by the upstream dockerhub staff)

Just giving my thoughts

While there is no official data, there is a non-negligible amount of Alpine users based on my first-hand observation. I think removing Alpine entirely will surely cause upset, and should be communicated beforehand (preferably with a notice period).
Even if the Alpine musl binary is experimental, musl builds are generally pretty good and rarely have issues. Just the depressingly slow build speed.
My recommendation is to adjust Alpine behavior to non-blocking over time. This aligns pretty well with the experimental status while providing options for Alpine userbase. We can adjust the behavior in multiple phases. e.g.,:
- phase 1: non-blocking behavior for security releases
- phase 2: non-blocking behavior for deprecations/new base release
- phase 3: non-blocking for all variants

Lastly, no matter what the final decision is, a communication/announcement via official channels is mandatory.

Regular WG meetings are sorely missed in cases like this. I can only hope that there won't be another security release until this matter is resolved properly

Note also that the Docker Getting Started workshop https://docs.docker.com/get-started/workshop/02_our_app/ is currently based on using the node:24-alpine image.

Any updates on this issue? been hanging for almost a month with no visible progress

Noting that in terms of security release delays since I would expect that security releases would normally be quite small and targetted it's likely that the ccache fix will mean that it doesn't take quite so long to rebuild. For example the latest 25 release built all unofficial builds in about an hour once it kicked off: https://unofficial-builds.nodejs.org/logs/202603031604-v25.8.0/)

It's good that fixes have speeded up builds. Hopefully this will mean that the situation of missing builds doesn't happen so often. The basic issue though still remains, due to Node.js' release policy:

Test failures on experimental platforms do not block releases.

That's true for the main releases from the project but does not necessarily cascade through to other areas like docker-node. We should probably adopt that formally in here too though.

That's true for the main releases from the project but does not necessarily cascade through to other areas like docker-node. We should probably adopt that formally in here too though.

I think that is the point of this issue, to determine and document how to react when the musl builds are missing. Wait for everything, or proceed with what's available.

Also possibly related to docs issue #2405 concerning manual instructions for updating Node.js version.

@mcollina

I have now submitted #2441 to document some of the things that were missing in the README:

describes how image tags can first appear without the related OS/ARCH images
explains why Alpine images may not initially be available for security releases

Several bugs in the update.sh script have been fixed, and it looks like it should now handle security releases correctly, although this will need to be checked at the next security release. The open PRs to fix this issue should be reviewed - they may not be necessary, or they may actually include additional useful enhancements.

Strategy discussions about whether Alpine should be included or not should be separated out of this issue, which was really more intended to clarify how things are currently handled.

BTW: https://nodejs.org/en/download now recommends downloading node:*-slim rather than node:*-alpine, which was an initiative started by @mcollina

The README now clarifies the topic "Document and implement strategy when musl releases (for Alpine) are missing", through the sections:

This issue is therefore resolved.

Parallel to the documentation changes, there were also some fixes applied to automation scripts.

Navigation Menu

Repository navigation

Document and implement strategy when musl releases (for Alpine) are missing #2363

Situation

Background

Suggestion

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Document and implement strategy when musl releases (for Alpine) are missing #2363

Description

Situation

Background

Suggestion

Activity

MikeMcC399 commented on Jan 27, 2026

MikeMcC399 commented on Jan 28, 2026

sxa commented on Feb 3, 2026

sxa commented on Feb 3, 2026

MikeMcC399 commented on Feb 3, 2026

sxa commented on Feb 4, 2026

ItsHarta commented on Feb 4, 2026

MikeMcC399 commented on Feb 4, 2026

ItsHarta commented on Feb 22, 2026

MikeMcC399 commented on Feb 22, 2026

sxa commented on Mar 5, 2026

MikeMcC399 commented on Mar 5, 2026

sxa commented on Mar 5, 2026

MikeMcC399 commented on Mar 5, 2026

MikeMcC399 commented on Mar 6, 2026

MikeMcC399 commented on Apr 2, 2026

MikeMcC399 commented on May 18, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions