Files
cloud-apache-container/docs/arm64-ols-family.md
shadowdaoandClaude Sonnet 5.5 044168f504 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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0185ukXi4YX5FxJGqhi6qab6
2026-11-20 06:32:23 -08:00

47 lines
2.8 KiB
Markdown

# 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.