fix(zoraxy): restore apk removed by the upstream image build (#3024)

* fix(zoraxy): restore apk removed by the upstream image build

Upstream's image build has ended with "rm -rf /sbin/apk" since v3.3.4. The
binary is deleted but /etc/apk (repositories, keys, world) and /lib/apk/db
survive, so package management is recoverable. The image also ships neither
bash nor curl, so ha_automodules.sh failed with "apt-get: not found / apk:
not found" (exit 127) and both architectures failed to build.

Restore the statically-linked apk binary from an Alpine build stage before the
shared module and package scripts run.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(zoraxy): keep BUILD_FROM a global build arg

Declaring the tools stage above the ARG lines scoped BUILD_FROM to that stage,
so the final FROM resolved to an empty base name. Move both global ARGs above
the first FROM.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(skill): record the global-ARG and vanishing-package-manager traps

Both cost a CI cycle on PR #3024: a tools stage inserted above ARG BUILD_FROM
demoted it to stage scope, and the upstream image had started deleting
/sbin/apk between releases.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

.claude/skills/hassio-addon-workflow/references/traps.md

@@ -163,6 +163,26 @@ the running image (`command -v <tool>`), and cross-check `/var/log/apt/history.l
 matching `apt-get install` line. An `if` block whose condition never matched leaves no trace and
 no error — one such block sat dead for weeks while appearing to guarantee driver verification.
 
+**Adding a build stage above `ARG BUILD_FROM` breaks the final `FROM`.** Global build args must
+be declared *before the first* `FROM` in the file; an `ARG` that follows one belongs to that stage
+only. Inserting a tools stage at the top of an add-on Dockerfile therefore demotes the
+`ARG BUILD_FROM` below it, and the final `FROM ${BUILD_FROM}` expands empty:
+`failed to solve: base name (${BUILD_FROM}) should not be blank`. Move `ARG BUILD_FROM` (and
+`ARG BUILD_VERSION`) above the new stage. `netalertx` does not hit this only because it hardcodes
+its base image instead of using `${BUILD_FROM}` — do not copy its ordering blindly
+(PR #3024).
+
+**A base image can lose its package manager between upstream releases.** Zoraxy v3.3.4 added
+`/sbin/apk` to the upstream cleanup step, so `ha_automodules.sh` failed with
+`apt-get: not found / apk: not found` (exit 127) on both architectures. The removal deleted only
+the binary — `/etc/apk` (repositories, keys, world) and `/lib/apk/db` survived, confirmed by a
+single `sbin/.wh.apk` whiteout in the layer — so copying `apk.static` from an
+`apk-tools-static` build stage restores package management in one line. Diff the upstream image
+configs across the two tags (`.history[].created_by` from the registry config blob) before
+theorising; it names the changed step exactly. Note `build_from` is often a floating `:latest`
+tag, so the builder's revert-on-failure does **not** restore a working build — the next rebuild
+fails identically until the Dockerfile is fixed (PR #3024).
+
 **Don't test for distro-specific filenames.** A guard on
 `/usr/share/vulkan/icd.d/intel_icd.x86_64.json` named a file Debian does not ship (it installs
 `intel_icd.json`), so fixing the arch variable alone would have turned dead code into a failing

zoraxy/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 3.3.3.1 (29-08-2026)
+- Fix build failure against the current upstream image: since v3.3.4 the upstream
+  build deletes /sbin/apk, so the shared module and package scripts had no package
+  manager and failed with "apt-get: not found / apk: not found" (exit 127). The
+  statically-linked apk binary is now restored from a build stage.
+
 ## 3.3.3 (2026-06-19)
 - Initial release
 - Zoraxy reverse proxy with web management UI (port 8000) for Home Assistant

zoraxy/Dockerfile

@@ -10,12 +10,27 @@
 #               /`
 #=== Home Assistant Addon ===#
 
+# Declared before the first FROM so they stay global build args, usable by the
+# FROM of the final stage below.
+ARG BUILD_FROM
+ARG BUILD_VERSION
+
+############################
+# 0 Tools stage (apk OK)   #
+############################
+# Upstream's image build ends with "rm -rf /sbin/apk" (added in v3.3.4), which
+# deletes the package manager binary but leaves /etc/apk (repositories, keys,
+# world) and /lib/apk/db intact. The shared build scripts below need a package
+# manager to install bash, curl and jq, none of which the image ships, so
+# restore apk from its statically-linked build. Keep this Alpine tag in sync
+# with the upstream base image (currently alpine-minirootfs-3.24.1).
+FROM alpine:3.24 AS ha_apk
+RUN apk add --no-cache apk-tools-static
+
 #################
 # 1 Build Image #
 #################
 
-ARG BUILD_FROM
-ARG BUILD_VERSION
 FROM ${BUILD_FROM}
 
 ##################
@@ -46,6 +61,9 @@ RUN if [ ! -f /bin/sh ] && [ -f /usr/bin/sh ]; then ln -s /usr/bin/sh /bin/sh; f
 # upstream working directory, so the configuration survives add-on updates.
 RUN sed -i 's#/opt/zoraxy/config#/config#g' /opt/zoraxy/entrypoint.py
 
+# Restore the package manager deleted by the upstream image build (see stage 0)
+COPY --from=ha_apk /sbin/apk.static /sbin/apk
+
 # Modules
 ARG MODULES="00-banner.sh"
 

zoraxy/config.yaml

@@ -6,7 +6,7 @@ image: ghcr.io/alexbelgium/zoraxy-{arch}
 name: Zoraxy
 slug: zoraxy
 url: https://github.com/alexbelgium/hassio-addons/tree/master/zoraxy
-version: "3.3.3"
+version: "3.3.3.1"
 init: false
 startup: services
 webui: "http://[HOST]:[PORT:8000]"