Skip to content

fix(docker): pin uWebSockets/uSockets tags so build works on Apple Silicon#38

Open
mudassaralichouhan wants to merge 1 commit into
hatefsystems:masterfrom
mudassaralichouhan:fix/dockerfile-pin-uwebsockets
Open

fix(docker): pin uWebSockets/uSockets tags so build works on Apple Silicon#38
mudassaralichouhan wants to merge 1 commit into
hatefsystems:masterfrom
mudassaralichouhan:fix/dockerfile-pin-uwebsockets

Conversation

@mudassaralichouhan

Copy link
Copy Markdown

Problem

docker compose build search-engine fails on Apple Silicon (M1/M2/M3 Macs)
when running with DOCKER_DEFAULT_PLATFORM=linux/amd64:

make: *** [GNUmakefile:7: examples] Error 255
write jobserver: Bad file descriptor
failed to solve: process "/bin/sh -c make -j$(nproc) WITH_EXAMPLES=0"
    did not complete successfully: exit code: 2

It also makes the build non-deterministic on any host — every rebuild
clones whatever HEAD of uWebSockets / uSockets happens to be on
master that day.

Root cause — two issues stacked

  1. Cloning master is unstable. A recent upstream change to
    uWebSockets made make build the examples/ directory by default;
    WITH_EXAMPLES=0 is no longer honoured by master's GNUmakefile.
    The examples themselves don't always compile cleanly with the host
    toolchain, so the build dies on [GNUmakefile:7: examples] Error 255.

  2. GNU make's jobserver is buggy under QEMU x86_64 emulation on ARM.
    -j$(nproc) produces write jobserver: Bad file descriptor inside
    the emulated container, causing the sub-make for examples to fail
    even when the target builds fine.

Fix

  • Pin to stable tags. uSockets v0.8.6 and uWebSockets v20.74.0
    are the last releases whose Makefiles still respect WITH_EXAMPLES=0.
  • -j1 on the uWebSockets step only. Sidesteps the QEMU jobserver
    bug. Adds a few seconds on native amd64; unlocks ARM hosts entirely.
  • examples= explicitly clears the examples target list as a
    belt-and-braces guard against future Makefile changes.
  • Build ARGs so the tags can be overridden at build time without
    editing the Dockerfile:
    docker build --build-arg UWEBSOCKETS_TAG=v20.77.0 .

Also adds a tracked .env.example documenting the env vars
docker-compose consumes (the real .env stays gitignored).

Test plan

Verified locally:

  • ✅ Native linux/amd64 (Linux x86_64): builds clean. uWebSockets step
    ~5s slower due to -j1; total build unchanged within noise.
  • ✅ Apple Silicon under DOCKER_DEFAULT_PLATFORM=linux/amd64: builds
    to completion (previously died at step 12/76).
export DOCKER_DEFAULT_PLATFORM=linux/amd64
docker compose build search-engine
# ...
# => exporting to image
# => => exporting layers
# Successfully built search-engine

Risk

Low. The pinned tags are public stable releases (v20.74.0, v0.8.6); the
-j1 change applies to a single ~30-second compile step. Nothing about
the resulting binaries changes — same library version was already what
master usually resolved to on stable days.

If a contributor wants newer uWS, they pass --build-arg UWEBSOCKETS_TAG=....

…licon

The build previously failed at the uWebSockets compile step when run
under `DOCKER_DEFAULT_PLATFORM=linux/amd64` on Apple Silicon hosts
(M1/M2/M3 Macs):

    make: *** [GNUmakefile:7: examples] Error 255
    write jobserver: Bad file descriptor

Two root causes:

1. The Dockerfile cloned uWebSockets from `master`, which is a moving
   target. A recent upstream change made the default `make` target build
   the `examples/` directory unconditionally — `WITH_EXAMPLES=0` is no
   longer honoured by master's GNUmakefile.

2. Under QEMU x86_64 emulation on ARM hosts, GNU make's jobserver gets
   corrupted with `-j$(nproc)`, causing "write jobserver: Bad file
   descriptor" and an examples sub-make failure.

Fix:

- Pin `uSockets` to v0.8.6 and `uWebSockets` to v20.74.0 — the last
  stable releases whose Makefile still respects `WITH_EXAMPLES=0`.
  Both pins are exposed as build ARGs (`USOCKETS_TAG`,
  `UWEBSOCKETS_TAG`) so they can be overridden without editing the
  Dockerfile.
- Build uWebSockets with `-j1` (only this one step) to side-step the
  emulated-make jobserver bug. Adds a few seconds on native amd64 but
  unlocks Apple Silicon builds.
- Also pass `examples=` to override the Makefile's example list as a
  belt-and-braces protection against future Makefile changes.

Also adds a tracked `.env.example` so contributors know which env vars
the compose stack consumes (the real `.env` stays gitignored).

Verified:
- Native x86_64 Linux: builds (jobs reduction adds ~5s to uWS step).
- Apple Silicon under DOCKER_DEFAULT_PLATFORM=linux/amd64: builds.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant