Merge pull request #22 from seonghobae/feature/multi-arch-images

feat: publish amd64 and arm64 images

Author: seonghobae

.github/workflows/docker-publish.yml

@@ -47,6 +47,11 @@ jobs:
         with:
           cosign-release: 'v2.2.4'
 
+      # Set up QEMU so Buildx can build arm64 images on the hosted runner
+      # https://github.com/docker/setup-qemu-action
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@68827325e0b33c7199eb31dd4e31fbe9023e06e3 # v3.0.0
+
       # Set up BuildKit Docker container builder to be able to build
       # multi-platform images and export cache
       # https://github.com/docker/setup-buildx-action
@@ -78,6 +83,7 @@ jobs:
         uses: docker/build-push-action@0565240e2d4ab88bba5387d719585280857ece09 # v5.0.0
         with:
           context: .
+          platforms: linux/amd64,linux/arm64
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}

AGENTS.md

@@ -11,6 +11,8 @@
 - Docker regression checks: `python3 -m unittest discover -s tests -v`
 - Local image build probe:
   `docker build --progress=plain -t opencpu-psychometrics .`
+- Local multi-arch workflow probe:
+  `docker buildx build --platform linux/amd64,linux/arm64 --progress=plain .`
 
 ## Code style
 

ARCHITECTURE.md

@@ -2,22 +2,30 @@
 
 ## Overview
 
-This repository ships a single Docker image for
+This repository ships a multi-architecture Docker image manifest for
 `ghcr.io/seonghobae/opencpu-psychometrics`.
 The image layers Ubuntu, OpenCPU, system libraries, Rust, and a
 large R package set used for psychometrics workloads.
-GitHub Actions verifies the repository by building and publishing
-that image from `.github/workflows/docker-publish.yml`.
+GitHub Actions verifies the repository by building the image on pull
+requests and by building plus publishing it from
+`.github/workflows/docker-publish.yml` on pushes to `main`, the nightly
+schedule, and release tag paths.
 
 ## Build Pipeline
 
 1. `.github/workflows/docker-publish.yml` runs
+   `docker/setup-qemu-action`, `docker/setup-buildx-action`, and
    `docker/build-push-action` on pushes, pull requests, and the
    nightly schedule.
 2. `Dockerfile` installs Ubuntu packages, OpenCPU from the official
    PPA, the CRAN apt repository, and the required R ecosystem
    packages.
-3. The workflow signs published images and uploads an SBOM when the
+3. Pull requests build the `linux/amd64` and `linux/arm64` targets for
+   verification without publishing them.
+4. Pushes, tags, and scheduled runs publish a manifest list for
+   `linux/amd64` and `linux/arm64`, so the same image tag resolves to
+   the native architecture on supported runners and hosts.
+5. The workflow signs published images and uploads an SBOM when the
    event is not a pull request.
 
 ## Stability Constraints

docs/plans/2026-03-11-multi-arch-images-design.md

@@ -0,0 +1,104 @@
+# Multi-Arch Images Design
+
+## Context
+
+- The repository currently publishes a single-platform image from
+  `.github/workflows/docker-publish.yml`.
+- Buildx is already configured, but the workflow does not declare
+  `platforms` and does not install QEMU.
+- Signing and SBOM steps already consume the digest from
+  `docker/build-push-action`, which can remain the manifest-list digest
+  in a multi-arch build.
+- The product goal is a GHCR image that is easy to consume from CI and
+  deployments; adding `linux/amd64` and `linux/arm64` aligns with that
+  goal without changing the runtime contract.
+
+## Constraints
+
+- Keep the Dockerfile behavior intact unless architecture-specific
+  breakage is observed.
+- Preserve current tag, signing, and SBOM behavior.
+- Keep the workflow pinned to explicit action SHAs.
+- Add tests before workflow changes.
+- Update `ARCHITECTURE.md` because build behavior changes.
+
+## Approaches
+
+### Approach A: Single Buildx job with QEMU and multi-platform output
+
+- Add `docker/setup-qemu-action`.
+- Set `platforms: linux/amd64,linux/arm64` in the existing
+  `docker/build-push-action` step.
+- Keep one workflow job and reuse the manifest-list digest for signing
+  and SBOM generation.
+
+Trade-offs:
+
+- Smallest diff and preserves the existing release flow.
+- Slowest step becomes slower, but caching and current downstream logic
+  stay simple.
+
+### Approach B: Matrix builds per architecture plus manifest assembly
+
+- Build amd64 and arm64 separately.
+- Publish per-arch images, then assemble a manifest list.
+
+Trade-offs:
+
+- Better isolation and clearer per-arch failures.
+- Considerably more workflow complexity and more moving parts for
+  signing/SBOM generation.
+
+### Approach C: Keep PR builds single-arch and publish multi-arch only on main/schedule
+
+- Use multi-arch on push/schedule and single-arch on pull requests.
+
+Trade-offs:
+
+- Reduces PR cost.
+- Leaves pull requests unable to validate the arm64 path, which weakens
+  confidence in the main publish path.
+
+## Recommendation
+
+Choose Approach A.
+
+It is the smallest safe change, matches the current workflow structure,
+and preserves current signing and SBOM logic. The repository already
+accepts long Docker builds, so the most important outcome is making both
+target architectures part of the same verified pipeline rather than
+adding a second publishing model.
+
+## Design
+
+- Add a workflow regression test in
+  `tests/test_docker_publish_workflow.py` that asserts the Docker
+  workflow sets up QEMU and declares both `linux/amd64` and
+  `linux/arm64`.
+- Update the Docker workflow to install QEMU before Buildx and to set the
+  multi-platform list on the existing build step.
+- Keep signing and SBOM logic on the existing digest output.
+- Update `ARCHITECTURE.md` to record that the publish pipeline now emits
+  a multi-architecture manifest list.
+
+## Error Handling
+
+- If arm64 package availability breaks later, the workflow should fail in
+  the existing build step rather than silently publishing amd64 only.
+- No fallback to single-arch publishing is added in this change; failure
+  should remain explicit.
+
+## Testing
+
+- Add failing tests in `tests/test_docker_publish_workflow.py` for QEMU
+  setup and the `platforms` declaration.
+- Run `python3 -m unittest discover -s tests -v`.
+- Run a YAML/workflow lint pass if available through the repo tooling.
+
+## Decisions
+
+- Safe default: validate both architectures in the same workflow rather
+  than treating arm64 as optional.
+- Safe default: workflow-only change first; no Dockerfile branching.
+- Safe default: keep PR builds multi-arch so the arm64 path is exercised
+  before merge.

docs/plans/2026-03-11-multi-arch-images.md

@@ -0,0 +1,144 @@
+# Multi-Arch Images Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use
+> superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Build and publish `opencpu-psychometrics` images for both
+`linux/amd64` and `linux/arm64` in the existing GitHub Actions
+workflow.
+
+**Architecture:** Keep the single Docker workflow job and extend it to
+build a multi-platform manifest list with QEMU + Buildx. Add
+regression tests that assert the workflow is configured for both target
+architectures, then update build documentation to reflect the new
+publish behavior.
+
+**Tech Stack:** GitHub Actions workflow YAML, Docker Buildx, QEMU,
+Python `unittest`
+
+---
+
+## Task 1: Add failing workflow tests
+
+**Files:**
+
+- Create: `tests/test_docker_publish_workflow.py`
+- Test: `tests/test_docker_publish_workflow.py`
+
+### Step 1: Write the failing test
+
+```python
+import pathlib
+import unittest
+
+
+WORKFLOW = (
+    pathlib.Path(__file__).resolve().parents[1]
+    / ".github/workflows/docker-publish.yml"
+)
+
+
+class DockerWorkflowMultiArchTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.content = WORKFLOW.read_text(encoding="utf-8")
+
+    def test_workflow_sets_up_qemu_for_cross_arch_builds(self) -> None:
+        self.assertIn("docker/setup-qemu-action", self.content)
+
+    def test_workflow_builds_amd64_and_arm64(self) -> None:
+        self.assertIn("platforms: linux/amd64,linux/arm64", self.content)
+```
+
+### Step 2: Run test to verify it fails
+
+Run: `python3 -m unittest tests.test_docker_publish_workflow -v`
+Expected: FAIL because QEMU and the multi-arch `platforms` line do
+not exist yet.
+
+### Step 3: Commit
+
+Do not commit yet.
+
+## Task 2: Update the workflow minimally
+
+**Files:**
+
+- Modify: `.github/workflows/docker-publish.yml`
+- Test: `tests/test_docker_publish_workflow.py`
+
+### Step 1: Write minimal implementation
+
+Add a pinned `docker/setup-qemu-action` step before Buildx and add:
+
+```yaml
+platforms: linux/amd64,linux/arm64
+```
+
+to the `docker/build-push-action` step.
+
+### Step 2: Run targeted tests to verify they pass
+
+Run: `python3 -m unittest tests.test_docker_publish_workflow -v`
+Expected: PASS
+
+### Step 3: Run the full test suite
+
+Run: `python3 -m unittest discover -s tests -v`
+Expected: PASS
+
+## Task 3: Update architecture docs
+
+**Files:**
+
+- Modify: `ARCHITECTURE.md`
+- Modify: `AGENTS.md` (if verification guidance needs to mention
+  workflow config tests)
+
+### Step 1: Document the new behavior
+
+Update `ARCHITECTURE.md` so the build pipeline section states that the
+workflow now emits a multi-architecture manifest list for amd64 and
+arm64.
+
+### Step 2: Verify docs remain lint-clean
+
+Run: `markdownlint-cli2 AGENTS.md ARCHITECTURE.md README.md`
+
+Run: `markdownlint-cli2 docs/plans/2026-03-11-multi-arch-images-design.md docs/plans/2026-03-11-multi-arch-images.md`
+
+Expected: PASS
+
+## Task 4: Final verification and commit
+
+**Files:**
+
+- Modify: `.github/workflows/docker-publish.yml`
+- Modify: `AGENTS.md`
+- Create: `tests/test_docker_publish_workflow.py`
+- Modify: `ARCHITECTURE.md`
+- Create: `docs/plans/2026-03-11-multi-arch-images-design.md`
+- Create: `docs/plans/2026-03-11-multi-arch-images.md`
+
+### Step 1: Run verification
+
+Run:
+
+```bash
+python3 -m unittest discover -s tests -v
+markdownlint-cli2 AGENTS.md ARCHITECTURE.md README.md
+markdownlint-cli2 docs/plans/2026-03-11-multi-arch-images-design.md docs/plans/2026-03-11-multi-arch-images.md
+```
+
+Expected: PASS
+
+### Step 2: Commit
+
+```bash
+git add .github/workflows/docker-publish.yml \
+  AGENTS.md \
+  tests/test_docker_publish_workflow.py \
+  ARCHITECTURE.md \
+  docs/plans/2026-03-11-multi-arch-images-design.md \
+  docs/plans/2026-03-11-multi-arch-images.md
+git commit -m "feat: publish multi-arch Docker images"
+```

tests/test_docker_publish_workflow.py

@@ -0,0 +1,40 @@
+import pathlib
+import unittest
+
+
+WORKFLOW = (
+    pathlib.Path(__file__).resolve().parents[1]
+    / ".github"
+    / "workflows"
+    / "docker-publish.yml"
+)
+
+
+class DockerPublishWorkflowTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.content = WORKFLOW.read_text(encoding="utf-8")
+        self.lines = self.content.splitlines()
+
+    def test_workflow_configures_qemu_before_buildx_for_multi_arch_images(self) -> None:
+        qemu_marker = "uses: docker/setup-qemu-action@"
+        buildx_marker = "uses: docker/setup-buildx-action@"
+
+        qemu_index = next(
+            index for index, line in enumerate(self.lines) if qemu_marker in line
+        )
+        buildx_index = next(
+            index for index, line in enumerate(self.lines) if buildx_marker in line
+        )
+
+        self.assertIn(qemu_marker, self.content)
+        self.assertIn(buildx_marker, self.content)
+        self.assertLess(qemu_index, buildx_index)
+
+    def test_workflow_builds_amd64_and_arm64_images(self) -> None:
+        self.assertIn("platforms:", self.content)
+        self.assertIn("linux/amd64", self.content)
+        self.assertIn("linux/arm64", self.content)
+
+
+if __name__ == "__main__":
+    unittest.main()