From 044168f5048674a5a9d01c268f7e15a4a5c569c2 Mon Sep 17 00:00:00 2001 From: Josh Knapp Date: Fri, 20 Nov 2026 06:32:23 -0800 Subject: [PATCH] ci: arm64-attach supports cac-lsphp, cac-litespeed and shared-ols Extends the dispatch-only attach workflow to the LiteSpeed family: same additive mechanism (amd64 manifest digest untouched), arm64 built from the packaged lsphp, with a parity gate (PHP version, SAPI, extensions, every ini value, OLS version) against the existing amd64 image before the tag is touched. Tests and docs/arm64-ols-family.md updated. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_0185ukXi4YX5FxJGqhi6qab6 --- .gitea/workflows/arm64-attach.yaml | 133 ++++++++++++++++++++--- docs/arm64-ols-family.md | 46 ++++++++ scripts/arm64-parity-probe.php | 22 ++++ scripts/tests/multiarch-workflow.test.py | 11 +- 4 files changed, 189 insertions(+), 23 deletions(-) create mode 100644 docs/arm64-ols-family.md create mode 100644 scripts/arm64-parity-probe.php diff --git a/.gitea/workflows/arm64-attach.yaml b/.gitea/workflows/arm64-attach.yaml index a4dbd96..43b88e6 100644 --- a/.gitea/workflows/arm64-attach.yaml +++ b/.gitea/workflows/arm64-attach.yaml @@ -1,6 +1,7 @@ name: Attach arm64 to an existing tag -run-name: attach arm64 to ${{ github.event.inputs.image }}:php${{ github.event.inputs.phpver }} -# Manual only (never on push): publishes an arm64 image for an EXISTING tag of cac or cac-fpm +run-name: attach arm64 to ${{ github.event.inputs.image }}:${{ github.event.inputs.phpver && format('php{0}', github.event.inputs.phpver) || 'latest' }} +# Manual only (never on push): publishes an arm64 image for an EXISTING tag of cac, cac-fpm, +# cac-lsphp, cac-litespeed (php) or shared-ols (:latest) # and merges it with the tag's CURRENT amd64 manifest into a new index. The amd64 image is # NOT rebuilt and NOT touched: its manifest digest (and config, layers, attestation) stay # byte-identical (with force=true the old arm64 is replaced and the amd64 attestation entry is not carried); only the tag's index digest changes. Use it to restore an arm64 entry that a @@ -14,12 +15,13 @@ on: workflow_dispatch: inputs: image: - description: 'cac or cac-fpm' + description: 'cac, cac-fpm, cac-lsphp, cac-litespeed or shared-ols' required: true type: string phpver: - description: 'PHP version without dots: 82, 83, 84, 85 or 86 (tag = php)' - required: true + description: 'PHP version without dots (tag = php): 82-86 for cac and cac-fpm, 82-85 for cac-lsphp and cac-litespeed. Leave empty for shared-ols (tag = latest).' + required: false + default: '' type: string force: description: 'true = replace an arm64 entry the tag already has (default: refuse)' @@ -42,6 +44,8 @@ jobs: uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0 # Inputs reach the shell via env only, and are regex-checked before use. + # family=rpm: AlmaLinux images (cac, cac-fpm). family=ols: the LiteSpeed family, built FROM + # litespeedtech/openlitespeed (cac-lsphp, cac-litespeed, shared-ols). - name: Validate inputs id: v env: @@ -50,23 +54,31 @@ jobs: IN_FORCE: ${{ github.event.inputs.force }} run: | set -euo pipefail + phpre='^8[2-6]$'; family=rpm; tag="php${IN_PHPVER}"; basephp="${IN_PHPVER}" case "$IN_IMAGE" in cac) dockerfile=Dockerfile; bins="/usr/sbin/httpd /usr/bin/php" ;; cac-fpm) dockerfile=Dockerfile.fpm; bins="/usr/sbin/php-fpm /usr/bin/php" ;; - *) echo "::error::image must be cac or cac-fpm"; exit 1 ;; + cac-lsphp|cac-litespeed) + family=ols; phpre='^8[2-5]$'; dockerfile="Dockerfile.${IN_IMAGE#cac-}" + bins="/usr/local/lsws/bin/openlitespeed /usr/local/lsws/lsphp${IN_PHPVER}/bin/lsphp" ;; + shared-ols) + family=ols; dockerfile=Dockerfile.shared-ols; tag=latest; basephp=83; phpre='^(83)?$' + bins="/usr/local/lsws/bin/openlitespeed" ;; + *) echo "::error::image must be cac, cac-fpm, cac-lsphp, cac-litespeed or shared-ols"; exit 1 ;; esac - [[ "$IN_PHPVER" =~ ^8[2-6]$ ]] || { echo "::error::phpver must be one of 82 83 84 85 86"; exit 1; } + [[ "$IN_PHPVER" =~ $phpre ]] || { echo "::error::phpver '${IN_PHPVER}' is not valid for ${IN_IMAGE} (pattern $phpre)"; exit 1; } case "${IN_FORCE:-false}" in true|false) ;; *) echo "::error::force must be true or false"; exit 1 ;; esac { echo "repo=repo.anhonesthost.net/cloud-hosting-platform/${IN_IMAGE}" - echo "tag=php${IN_PHPVER}" + echo "tag=${tag}" echo "image=${IN_IMAGE}" - echo "phpver=${IN_PHPVER}" + echo "phpver=${basephp}" + echo "family=${family}" echo "dockerfile=${dockerfile}" echo "bins=${bins}" echo "force=${IN_FORCE:-false}" } >> "$GITHUB_OUTPUT" - echo "attach arm64 to ${IN_IMAGE}:php${IN_PHPVER} (force=${IN_FORCE:-false})" + echo "attach arm64 to ${IN_IMAGE}:${tag} (family=${family}, force=${IN_FORCE:-false})" - name: Login to Gitea uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0 @@ -78,7 +90,8 @@ jobs: - name: Resolve base image digest (Docker Hub, direct) id: base env: - BASE_TAG: almalinux/10-base:latest + # OLS family: same pin as build-push.yaml (OLS_VERSION 1.8.4; shared-ols uses the lsphp83 tag). + BASE_TAG: ${{ steps.v.outputs.family == 'ols' && format('litespeedtech/openlitespeed:1.8.4-lsphp{0}', steps.v.outputs.phpver) || 'almalinux/10-base:latest' }} run: | set -uo pipefail if ref=$(.gitea/scripts/resolve-base-image.sh "$BASE_TAG") && [[ "$ref" =~ ^[a-z0-9][a-z0-9._/-]*@sha256:[0-9a-f]{64}$ ]]; then @@ -145,6 +158,7 @@ jobs: # Same php.net floor as the normal build: the Dockerfile fails on anything older. - name: Resolve current PHP release from php.net + if: steps.v.outputs.family == 'rpm' id: phpmin env: PHPVER: ${{ steps.v.outputs.tag }} @@ -157,6 +171,47 @@ jobs: echo "php.net current ${branch}: ${min}" echo "min=${min}" >> "$GITHUB_OUTPUT" + # OLS family (cac-lsphp, cac-litespeed): the arm64 image is built from the LiteSpeed PACKAGED + # lsphp (apt noble arm64), not from php.net source: LiteSpeed now ships the same PHP release + # the amd64 php.net-source images carry, so version, extensions and ini defaults are equal; the + # parity step below PROVES that against the existing amd64 image and refuses otherwise. + # EXPECT_* come from the arm64 index (the amd64 index may differ by hours). docs/arm64-ols-family.md + - name: Resolve build args + id: args + env: + FAMILY: ${{ steps.v.outputs.family }} + IMAGE: ${{ steps.v.outputs.image }} + PHPVER: ${{ steps.v.outputs.phpver }} + BASE_IMAGE: ${{ steps.base.outputs.image }} + PKG_CACHE: ${{ steps.pkgcache.outputs.url }} + BUST: ${{ steps.bust.outputs.value }} + PHPMIN: ${{ steps.phpmin.outputs.min }} + run: | + set -euo pipefail + { + echo "list<&2; exit 1; } + php="${pkg%%-*}" + [[ "$php" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "::error::malformed PHP version '${php}'" >&2; exit 1; } + echo "CACHE_BUST=${BUST}" + echo "EXPECT_LSPHP_PKG=${pkg}" + echo "EXPECT_PHP_VERSION=${php}" + echo "lsphp${PHPVER} arm64 package ${pkg}" >&2 + fi + fi + echo "ARGS_EOF" + } >> "$GITHUB_OUTPUT" + # arm64 only, pushed UNTAGGED by digest. Required here (this run exists only for it): a # failure fails the run and the tag is not touched. - name: Build arm64 (push by digest) @@ -166,12 +221,7 @@ jobs: with: file: ./${{ steps.v.outputs.dockerfile }} platforms: linux/arm64 - build-args: | - PHPVER=${{ steps.v.outputs.phpver }} - CACHE_BUST=${{ steps.bust.outputs.value }} - BASE_IMAGE=${{ steps.base.outputs.image }} - PKG_CACHE=${{ steps.pkgcache.outputs.url }} - EXPECT_PHP_MIN=${{ steps.phpmin.outputs.min }} + build-args: ${{ steps.args.outputs.list }} outputs: type=image,name=repo.anhonesthost.net/cloud-hosting-platform/${{ steps.v.outputs.image }},push-by-digest=true,name-canonical=true,push=true # The arm64 entry must contain AArch64 binaries and the existing amd64 entry x86-64 ones: @@ -191,8 +241,9 @@ jobs: python3 -I scripts/verify-image-arch.py --image "$REPO@$ARM64_DIGEST" --platform linux/arm64 "${bins[@]}" python3 -I scripts/verify-image-arch.py --image "$REPO@$AMD64" --platform linux/amd64 "${bins[@]}" - # The new arm64 was built now, the amd64 entry earlier: refuse a PHP version skew between them. + # The new arm64 was built now, the amd64 entry earlier: refuse a version skew between them. - name: PHP version parity (amd64 native, arm64 under QEMU) + if: steps.v.outputs.family == 'rpm' env: REPO: ${{ steps.v.outputs.repo }} TAG: ${{ steps.v.outputs.tag }} @@ -212,6 +263,52 @@ jobs: [[ "$want" =~ ^[0-9]+\.[0-9]+\.[0-9]+ ]] || { echo "::error::cannot read the amd64 PHP version"; exit 1; } [ "$want" = "$got" ] || { echo "::error::PHP version differs between the existing amd64 (${want}) and the new arm64 (${got}); not attaching. The amd64 image needs a rebuild first."; exit 1; } + # OLS family: the arm64 (packaged lsphp / OLS from the LiteSpeed repo and base image) must be + # observably the SAME PHP as the existing amd64 image (php.net-source or packaged): identical + # PHP_VERSION, SAPI, loaded extensions + versions and EVERY ini value, both with the image's + # config and with `-n` (compiled-in defaults). scripts/arm64-parity-probe.php runs natively on + # amd64 and under QEMU (a throwaway BuildKit RUN) on arm64; any difference prints as a diff + # and fails the run before the tag is touched. shared-ols runs no PHP: openlitespeed -v only. + - name: "Parity - same PHP / OLS as the existing amd64 image" + if: steps.v.outputs.family == 'ols' + env: + REPO: ${{ steps.v.outputs.repo }} + IMAGE: ${{ steps.v.outputs.image }} + PHPVER: ${{ steps.v.outputs.phpver }} + ARM64_DIGEST: ${{ steps.arm64.outputs.digest }} + AMD64: ${{ steps.plan.outputs.amd64 }} + run: | + set -euo pipefail + work=$(mktemp -d); mkdir -p "$work/ctx" "$work/out" "$work/amd" + cp scripts/arm64-parity-probe.php "$work/ctx/probe.php" + # OpenLiteSpeed: same release and module versions. The "(BUILD built: )" stamp is LiteSpeed's + # own per-arch build time (differs by design), so it is stripped before comparing. + olsv='/usr/local/lsws/bin/openlitespeed -v 2>&1 | sed "s/ (BUILD built:.*)//"' + docker run --rm --platform linux/amd64 --entrypoint sh "$REPO@$AMD64" -c "$olsv" > "$work/amd/ols.txt" + printf 'FROM %s@%s AS src\nRUN (%s) > /ols.txt\nFROM scratch\nCOPY --from=src /ols.txt /ols.txt\n' "$REPO" "$ARM64_DIGEST" "$olsv" | + docker buildx build --platform linux/arm64 --output "type=local,dest=$work/out" -f - "$work/ctx" + echo "amd64 OLS: $(head -1 "$work/amd/ols.txt"); arm64 OLS: $(head -1 "$work/out/ols.txt")" + grep -q '^LiteSpeed/' "$work/amd/ols.txt" || { echo "::error::cannot read the amd64 openlitespeed version"; exit 1; } + diff -u "$work/amd/ols.txt" "$work/out/ols.txt" || { echo "::error::openlitespeed version/modules differ between amd64 and arm64; not attaching"; exit 1; } + [ "$IMAGE" != shared-ols ] || { echo "parity OK: OpenLiteSpeed version and modules identical (shared-ols runs no PHP)"; exit 0; } + ls_bin="/usr/local/lsws/lsphp${PHPVER}/bin/lsphp" + for mode in cfg n; do + flag=""; [ "$mode" = n ] && flag="-n" + # probe piped over stdin (not a bind mount: the job's docker daemon cannot see the workspace) + docker run --rm -i --platform linux/amd64 --entrypoint sh "$REPO@$AMD64" -c "cat > /tmp/probe.php; $ls_bin $flag /tmp/probe.php" < "$work/ctx/probe.php" > "$work/amd/$mode.txt" + done + # the same two runs on arm64, inside one BuildKit build (no binfmt for `docker run` here) + printf 'FROM %s@%s AS src\nCOPY probe.php /probe.php\nRUN %s /probe.php > /cfg.txt && %s -n /probe.php > /n.txt\nFROM scratch\nCOPY --from=src /cfg.txt /n.txt /\n' "$REPO" "$ARM64_DIGEST" "$ls_bin" "$ls_bin" | + docker buildx build --platform linux/arm64 --output "type=local,dest=$work/out" -f - "$work/ctx" + rc=0 + for mode in cfg n; do + echo "== $mode: $(head -1 "$work/amd/$mode.txt") (amd64) vs $(head -1 "$work/out/$mode.txt") (arm64); $(grep -c '^ext ' "$work/amd/$mode.txt") / $(grep -c '^ext ' "$work/out/$mode.txt") extensions, $(grep -c '^ini ' "$work/amd/$mode.txt") / $(grep -c '^ini ' "$work/out/$mode.txt") ini values" + grep -q '^PHP_VERSION=[0-9]' "$work/amd/$mode.txt" || { echo "::error::cannot read the amd64 probe output ($mode)"; exit 1; } + diff -u "$work/amd/$mode.txt" "$work/out/$mode.txt" || rc=1 + done + [ "$rc" = 0 ] || { echo "::error::the new arm64 is not the same PHP as the existing amd64 image (diff above); not attaching. Rebuild amd64 or fix the arm64 build first."; exit 1; } + echo "parity OK: version, SAPI, extensions and every ini value identical" + # Re-creates the tag index: existing amd64 entries by digest + the new arm64. Aborts if the # tag moved since the plan; verifies the amd64 manifest digest is unchanged afterwards. - name: Attach (create the new index) diff --git a/docs/arm64-ols-family.md b/docs/arm64-ols-family.md new file mode 100644 index 0000000..a2cdcda --- /dev/null +++ b/docs/arm64-ols-family.md @@ -0,0 +1,46 @@ +# arm64 for the LiteSpeed family (cac-lsphp, cac-litespeed, shared-ols) + +`arm64-attach.yaml` (manual dispatch, trunk only) attaches an arm64 image to an EXISTING tag +without rebuilding or touching the amd64 image. Inputs: `image` = cac-lsphp | cac-litespeed | +shared-ols, `phpver` = 82..85 (empty for shared-ols, whose tag is `latest`). + +## How the arm64 image is built + +Same Dockerfile (`Dockerfile.lsphp`, `Dockerfile.litespeed`, `Dockerfile.shared-ols`), same +`OLS_VERSION=1.8.4` base (`litespeedtech/openlitespeed:1.8.4-lsphpNN`, which has an arm64 variant), +built under QEMU on the x86 runner and pushed by digest, then merged into the tag's index. + +The published amd64 tags were built from php.net source (`org.whp.lsphp-source=php.net`, emergency +path, docs/lsphp-source-emergency.md). The arm64 image is built from the PACKAGED lsphp (LiteSpeed +apt, noble arm64), not from source, because: + +* LiteSpeed now ships the same PHP release for both architectures (8.2.36, 8.3.37, 8.4.28, 8.5.13, + all `-1+noble`), so the PHP version is identical to the amd64 image; +* compiling PHP under QEMU is slow and the source path's gates compare against a packaged lsphp + that is no longer older than the source one; +* the result is checked, not assumed: the workflow runs `scripts/arm64-parity-probe.php` natively in + the existing amd64 image and under QEMU in the new arm64 image and FAILS the run (tag untouched) + on any difference in PHP_VERSION, SAPI, the loaded extension list and versions, or any of the + ~350 ini values (with the image's config and with `-n`). It also compares the OpenLiteSpeed + version and module versions (LiteSpeed's per-arch "BUILD built:" stamp is ignored). + Measured 2026-11-20 on cac-lsphp:php85: 418 lines identical. + +`EXPECT_LSPHP_PKG` / `EXPECT_PHP_VERSION` come from the arm64 repo index +(`scripts/lsphp-repo-version.sh PHPVER arm64`), not the amd64 one. + +Labels differ by design: the arm64 image says `org.whp.lsphp-source=litespeed-apt` and its own +package version. `php-emergency-guard.sh` reads the amd64 child only, so it is unaffected. + +## Other guards (same as cac / cac-fpm) + +plan pre-check (tag exists, one amd64 entry, no arm64 yet unless `force=true`), ELF machine check of +both platforms (openlitespeed + lsphp), tag-moved check, amd64 manifest digest verified unchanged +after the attach, runs serialised (concurrency group `arm64-attach`). `latest` is re-pointed only +if it was an exact alias of php85. + +## Maintenance caveat + +`build-push.yaml` and `lsphp-source-emergency.yaml` (without `build_arm64`) still publish these +tags amd64-only. A rebuild therefore replaces the tag with an index without arm64: re-run the +attach for that tag afterwards (the plan step refuses nothing in that case, the tag simply has no +arm64 entry again). Wiring an arm64 leg into those jobs is the permanent fix. diff --git a/scripts/arm64-parity-probe.php b/scripts/arm64-parity-probe.php new file mode 100644 index 0000000..00ffb70 --- /dev/null +++ b/scripts/arm64-parity-probe.php @@ -0,0 +1,22 @@ + $v) { + echo 'ini ', $k, '=', var_export($v, true), "\n"; +} diff --git a/scripts/tests/multiarch-workflow.test.py b/scripts/tests/multiarch-workflow.test.py index 7dbf7a0..865f58a 100755 --- a/scripts/tests/multiarch-workflow.test.py +++ b/scripts/tests/multiarch-workflow.test.py @@ -397,14 +397,15 @@ class AttachWorkflow(unittest.TestCase): self.assertNotIn('${{', blk) # everything reaches the script through env: self.assertNotIn('github.event.inputs', self.job.split('Validate inputs', 1)[1].split('Login to Gitea', 1)[1]) - def test_only_images_cac_and_cac_fpm_and_php82_to_86(self): + def test_only_the_five_known_images_and_php_ranges(self): v = step(self.job, 'Validate inputs') self.assertRegex(v, r'cac\)\s+dockerfile=Dockerfile;') self.assertRegex(v, r'cac-fpm\)\s+dockerfile=Dockerfile\.fpm;') self.assertIn('^8[2-6]$', v) - self.assertEqual(re.findall(r'(?m)^ ([a-z-]+)\)', v), ['cac', 'cac-fpm']) - self.assertNotIn('litespeed', v) - self.assertNotIn('lsphp', v) + self.assertRegex(v, r'cac-lsphp\|cac-litespeed\)') + self.assertRegex(v, r'shared-ols\)') + self.assertIn("^8[2-5]$", v) # OLS family: 82-85 only + self.assertEqual(re.findall(r'(?m)^ ([a-z-]+)\)', v), ['cac', 'cac-fpm', 'shared-ols']) def test_arm64_only_push_by_digest_no_tags(self): self.assertEqual(len(re.findall(r'platforms: linux/', self.job)), 1) @@ -420,7 +421,7 @@ class AttachWorkflow(unittest.TestCase): def test_nothing_but_the_script_writes_a_tag(self): for bad in ('imagetools create', 'docker push', 'docker tag', '/cac:latest', '/cac-fpm:latest', 'ghcr.io'): self.assertNotIn(bad, self.job, bad) - self.assertEqual(self.job.count('docker buildx build'), 1) # only the local PHP-version probe + self.assertEqual(self.job.count('docker buildx build'), 3) # only the local probes: php version (rpm), OLS version (shared-ols), lsphp probe self.assertIn('type=local,dest=', self.job) self.assertNotIn('--push', self.job) self.assertEqual(self.job.count('scripts/attach-arm64-index.sh'), 2) # plan (read-only) + attach -- 2.52.0