Merge pull request 'feat: refuse a tag without an image for the host's platform' (#10) from feat/arm64-preflight into main
CI / check (push) Successful in 14s

This commit was merged in pull request #10.
This commit is contained in:
christianmanivong committed 2026-10-11 06:39:07 +00:00
commit a7e3617291
3 files changed
+233 -2

No files matched your search

+12 -1
View File
@@ -26,6 +26,14 @@ start, and database migrations run from that same image.
tag you deploy. The engine image must carry its compose files under `/app/deploy/`.
Tags built before that change are refused with a clear message.
**Raspberry Pi and other arm64 hosts:** a Raspberry Pi 3, 4, 5 or Zero 2 W with a 64-bit
OS can be a target. Nothing changes in `deploy.env`: each host pulls the variant for its
own platform. netOrk publishes arm64 images for releases only, from 0.34.0 on (`latest`,
`X.Y.Z`). `latest-dev`, `main-<sha>`, `feature-<branch>` and older releases are amd64 only,
and a deploy of such a tag to an arm64 host is refused before the host is touched. The
images on the host (`postgres`, `redis`, `apt-cacher-ng`, `signal-api`) exist for arm64
as well.
## Setup
```bash
@@ -76,7 +84,10 @@ started earlier pulls whatever image the registry held before, which is stale.
ssh session, so a deploy that fails, is interrupted or loses its connection frees it
on its own. A host without `flock` is deployed without the lock, with a warning.
1. Logs in to the registry. The password travels over ssh's stdin, never on a command
line.
line. Then it checks that the tag has an image for the host's platform (`docker
version`, `docker manifest inspect`): engine, and on UI servers ui. If not, for
example `latest-dev` on a Raspberry Pi, it stops here and says which tags would work.
If the registry's answer can't be read, the pull below decides.
2. Pulls the engine image and copies `docker-compose.yml` and
`docker-compose.registry.yml` out of it into `~/netork/`.
3. Pulls the netOrk images, then force-recreates the API, the workers, `netork-beat`,
+55 -1
View File
@@ -73,6 +73,53 @@ run_remote() {
fi
}
# ── The host's platform ──────────────────────────────────────────────────────
# From 0.34.0 on, netOrk's releases (X.Y.Z, latest) are published for
# linux/amd64 and linux/arm64, so a Raspberry Pi with a 64-bit OS runs them
# (NetOrk/netork#934). latest-dev, main-<sha>, feature-<branch> and every older
# release are amd64 only. On a Pi those fail at the first pull with "no
# matching manifest for linux/arm64/v8", which names neither the cause nor a
# tag that would work. So the host's architecture is compared with the
# platforms the registry lists for the tag, after the login (the registry may
# be private) and before anything on the host changes.
#
# Only a definite mismatch stops the deploy. When the registry says nothing
# readable (no `docker manifest`, a missing tag, a single-platform manifest),
# the pull decides, as before.
#
# check_platform <server> <version> <repositories>
check_platform() {
local server=$1 version=$2 repos=$3 answer arch missing
# shellcheck disable=SC2029 # registry, version and repositories expand here
answer="$(ssh -n "$server" "docker version --format 'arch={{.Server.Arch}}' 2>/dev/null; \
for r in ${repos}; do echo \"repo=\$r\"; \
docker manifest inspect '${REGISTRY_HOST}/netork/'\$r':${version}' 2>/dev/null; done; true")" || return 0
arch="$(sed -n 's/^arch=//p' <<< "$answer" | head -1)"
[[ -n "$arch" ]] || return 0
# One line per repository whose listed platforms lack this host's.
missing="$(awk -v want="$arch" '
/^repo=/ { repo = substr($0, 6); seen[repo] = ""; next }
repo != "" && match($0, /"architecture": *"[^"]+"/) {
a = substr($0, RSTART, RLENGTH); sub(/^"architecture": *"/, "", a); sub(/"$/, "", a)
if (a != "unknown") seen[repo] = seen[repo] " linux/" a
}
END {
for (r in seen)
if (seen[r] != "" && index(seen[r] " ", " linux/" want " ") == 0)
print r " has only" seen[r]
}' <<< "$answer")"
if [[ -n "$missing" ]]; then
echo "[${server}] Refusing to deploy '${version}': ${server} is linux/${arch}, and" >&2
while IFS= read -r line; do echo "[${server}] ${line}" >&2; done <<< "$missing"
echo "[${server}] netOrk publishes linux/arm64 for releases from 0.34.0 on (latest, X.Y.Z)." >&2
echo "[${server}] latest-dev, main-<sha> and feature-<branch> are linux/amd64 only." >&2
return 1
fi
}
# ── One deploy per host at a time ────────────────────────────────────────────
# Several sessions deploy to the same test server, and two runs used to overlap:
# on 2026-10-05 two `up -d --force-recreate` recreated each other's containers,
@@ -225,6 +272,12 @@ deploy_steps() {
| ssh "$SERVER" "docker login '${REGISTRY_HOST}' -u '${SERVER_USER}' --password-stdin 2>&1" \
| sed "s/^/[${SERVER}] /"
local REPOS="engine"
if [[ " $UI_SERVER " == *" $SERVER "* ]]; then
REPOS="engine ui"
fi
check_platform "$SERVER" "$SERVER_VERSION" "$REPOS"
# The compose files are versioned with the images they start, so they are
# taken from the engine image of this very tag rather than from whatever
# checkout happens to run the deploy. Both are written to .new first and only
@@ -412,7 +465,8 @@ REMOTE_ENV
echo "Deploying from ${REGISTRY_HOST} to: ${SERVERS[*]}"
export -f deploy_server deploy_steps hold_host_lock release_host_lock _validate_version run_remote
export -f deploy_server deploy_steps hold_host_lock release_host_lock _validate_version run_remote \
check_platform
export UI_SERVER REGISTRY_HOST REGISTRY_USER REGISTRY_PASSWORD NETORK_VERSION VERSION_OVERRIDE \
VALID_VERSION_RE COMPOSE_FILES DEPLOY_LOCK_WAIT
# Export all per-server credential vars so subshells can resolve them
+166
View File
@@ -0,0 +1,166 @@
"""A host gets a tag only if the tag has an image for the host's platform (NetOrk/netork#934).
From 0.34.0 on, netOrk's releases (`X.Y.Z`, `latest`) are published for
linux/amd64 and linux/arm64, so a Raspberry Pi with a 64-bit OS can run netOrk.
Everything else is amd64 only: `latest-dev`, `main-<sha>`, `feature-<branch>`,
and every release before 0.34.0. On a Pi such a tag fails at the first `docker
pull` with "no matching manifest for linux/arm64/v8 in the manifest list
entries", which names neither the cause nor a tag that would work.
So right after the registry login the script asks the host for its
architecture, and the registry for the platforms of the engine (and, on UI
servers, the ui) image, and refuses before anything on the host changes.
When the registry says nothing it can read, the check stays out of the way and
the pull decides, as before.
The remote side is a fake `ssh` that records every command and answers the
platform question from FAKE_PLATFORMS.
"""
from __future__ import annotations
import os
import subprocess
from pathlib import Path
DEPLOY = Path(__file__).resolve().parent.parent / "deploy.sh"
_FAKE_SSH = """#!/bin/sh
for arg in "$@"; do cmd="$arg"; done
# The host lock's holder runs for real, here (test_deploy_host_lock.py).
case "$cmd" in *.deploy.lock*) exec sh -c "$cmd" ;; esac
cat > /dev/null
printf '%s\\n----\\n' "$cmd" >> "{state}/commands"
case "$cmd" in
*"docker manifest inspect"*) cat "{state}/platforms" ;;
esac
exit 0
"""
def _index(*architectures: str) -> str:
"""`docker manifest inspect` output for an OCI index, as docker prints it."""
entries = ",\n".join(
" {\n"
' "mediaType": "application/vnd.oci.image.manifest.v1+json",\n'
' "platform": {\n'
f' "architecture": "{arch}",\n'
' "os": "linux"\n'
" }\n"
" }"
for arch in architectures
)
return (
'{\n "schemaVersion": 2,\n'
' "mediaType": "application/vnd.oci.image.index.v1+json",\n'
f' "manifests": [\n{entries}\n ]\n}}\n'
)
AMD64_ONLY = _index("amd64", "unknown")
BOTH = _index("amd64", "unknown", "arm64", "unknown")
def _deploy(
tmp_path: Path, answer: str, *, version: str = "0.34.0", ui: bool = False
) -> tuple[subprocess.CompletedProcess[str], list[str]]:
bin_dir = tmp_path / "bin"
bin_dir.mkdir()
fake = bin_dir / "ssh"
fake.write_text(_FAKE_SSH.replace("{state}", str(tmp_path)))
fake.chmod(0o755)
(tmp_path / "platforms").write_text(answer)
env = {
"PATH": f"{bin_dir}:{os.environ['PATH']}",
"HOME": str(tmp_path),
"DEPLOY_ENV_FILE": "/dev/null",
"REGISTRY_HOST": "registry.example",
"NETORK_VERSION": version,
}
if ui:
env["UI_SERVER"] = "testhost"
result = subprocess.run(
["bash", str(DEPLOY), "testhost"],
env=env,
stdin=subprocess.DEVNULL,
capture_output=True,
text=True,
timeout=60,
check=False,
)
commands = (tmp_path / "commands").read_text().split("\n----\n")
return result, commands
def _fetched_compose_files(commands: list[str]) -> bool:
return any("/app/deploy/" in c for c in commands)
def test_an_amd64_only_tag_is_refused_on_an_arm64_host(tmp_path: Path) -> None:
answer = "arch=arm64\nrepo=engine\n" + AMD64_ONLY
result, commands = _deploy(tmp_path, answer, version="latest-dev")
assert result.returncode != 0
assert "latest-dev" in result.stderr
assert "linux/arm64" in result.stderr
assert "engine" in result.stderr
# Names what would work instead.
assert "0.34.0" in result.stderr
assert not _fetched_compose_files(commands), "the host was touched before the refusal"
def test_a_release_with_arm64_deploys_on_an_arm64_host(tmp_path: Path) -> None:
answer = "arch=arm64\nrepo=engine\n" + BOTH
result, commands = _deploy(tmp_path, answer)
assert result.returncode == 0, result.stderr
assert _fetched_compose_files(commands)
def test_an_amd64_host_deploys_an_amd64_only_tag(tmp_path: Path) -> None:
answer = "arch=amd64\nrepo=engine\n" + AMD64_ONLY
result, _ = _deploy(tmp_path, answer, version="latest-dev")
assert result.returncode == 0, result.stderr
def test_the_ui_is_checked_on_a_ui_server(tmp_path: Path) -> None:
answer = "arch=arm64\nrepo=engine\n" + BOTH + "repo=ui\n" + AMD64_ONLY
result, commands = _deploy(tmp_path, answer, ui=True)
assert result.returncode != 0
assert "ui" in result.stderr
assert not _fetched_compose_files(commands)
(check,) = [c for c in commands if "docker manifest inspect" in c]
assert "for r in engine ui;" in check
def test_the_ui_is_not_asked_for_on_other_servers(tmp_path: Path) -> None:
answer = "arch=arm64\nrepo=engine\n" + BOTH
_, commands = _deploy(tmp_path, answer)
(check,) = [c for c in commands if "docker manifest inspect" in c]
assert "for r in engine;" in check
def test_the_check_comes_after_the_login_and_before_the_compose_files(tmp_path: Path) -> None:
"""The registry may be private: the host can only ask it once logged in."""
answer = "arch=arm64\nrepo=engine\n" + BOTH
_, commands = _deploy(tmp_path, answer)
login = next(i for i, c in enumerate(commands) if "docker login" in c)
check = next(i for i, c in enumerate(commands) if "docker manifest inspect" in c)
fetch = next(i for i, c in enumerate(commands) if "/app/deploy/" in c)
assert login < check < fetch
def test_a_registry_answer_it_cannot_read_leaves_it_to_the_pull(tmp_path: Path) -> None:
"""An older docker without `manifest`, a missing tag, a single-platform
manifest: the check says nothing, and the pull reports what is wrong."""
for answer in ("", "arch=arm64\nrepo=engine\n", 'arch=arm64\nrepo=engine\n{"config": {}}\n'):
case = tmp_path / str(len(answer))
case.mkdir()
result, commands = _deploy(case, answer)
assert result.returncode == 0, (answer, result.stderr)
assert _fetched_compose_files(commands)