Skip to content

ci: build and verify the Docker image on amd64 and arm64 - #22

Open
mgd43b wants to merge 1 commit into
joungminsung:mainfrom
mgd43b:claude/dockerfile-multi-arch-99eb02
Open

mgd43b wants to merge 1 commit into
joungminsung:mainfrom
mgd43b:claude/dockerfile-multi-arch-99eb02

Conversation

@mgd43b

@mgd43b mgd43b commented Aug 8, 2026

Copy link
Copy Markdown

Summary

Adds a Docker workflow that builds the image for linux/amd64 and linux/arm64 and verifies each one actually works, plus docs for building a multi-platform image.

One note on the issue's premise: the Dockerfile is not x86-only today. The case "$node_arch" block added in 6358786 already installs the arm64 Rollup/LanceDB packages, and optionalDependencies already lists @lancedb/lancedb-linux-arm64-gnu. I built and ran the image on an M-series Mac with no changes and it works. So the real gap was that nothing exercised the ARM64 path — it could regress silently — and nothing documented it. This PR closes that gap rather than changing the Dockerfile.

Type of Change

  • New feature (CI coverage)
  • Documentation update

Related Issue

Closes #4

Why native runners instead of --platform linux/amd64,linux/arm64

The issue suggests a single QEMU build with both platforms. I tried that first and it does not work reliably: esbuild is a Go binary, and Go binaries abort under qemu-user partway through the Vite build.

@opendocuments/web:build: fatal error: lfstack.push
@opendocuments/web:build: [vite:esbuild] The service was stopped

So the workflow builds each platform on a native runner instead — ubuntu-latest for amd64, ubuntu-24.04-arm for arm64 (free for public repos). This is also much faster than emulating the monorepo build. docker buildx build --platform linux/amd64,linux/arm64 is still the right command for a user on their own machine, and it is what the README now documents.

Test Plan

Verified locally on an Apple Silicon Mac (linux/arm64, built natively):

  • docker buildx build --platform linux/arm64 — succeeds
  • docker image inspect --format '{{.Architecture}}'arm64
  • require('@lancedb/lancedb') and better-sqlite3 load and run a real query inside the container → arch: arm64, sqlite rows: 1
  • Container boots and GET /healthz returns {"status":"ok"} with HEALTHCHECK reporting healthy, using no model config (it degrades to stub models and still serves)

These are exactly the three checks the workflow runs, so amd64 gets the same treatment on a native x86 runner. I could not verify the amd64 leg locally for the QEMU reason above — that one runs for the first time on this PR.

.github/workflows/docker.yml passes actionlint.

Notes

  • The workflow is build-and-verify only — it does not push anywhere. If you'd like it to publish a multi-arch manifest to GHCR on main/tags, I'm happy to add that; I left it out since it's a packaging decision that's yours to make.
  • paths: filters keep it off doc-only PRs.
  • No changeset: nothing here affects a published package.

The Dockerfile already selects per-architecture native packages, but nothing
exercised the ARM64 path, so it could regress unnoticed and Apple Silicon
support was undocumented.

Add a Docker workflow that builds the image for linux/amd64 and linux/arm64
on native runners, then verifies each image reports the expected architecture,
loads the LanceDB and better-sqlite3 native modules, and serves /healthz.

Native runners rather than QEMU: esbuild is a Go binary and aborts under
qemu-user with 'fatal error: lfstack.push' during the Vite build.

Closes joungminsung#4
Copilot AI lite review requested due to automatic review settings August 8, 2026 04:51

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds CI coverage to ensure the repo’s Docker image is continuously built and smoke-tested on both linux/amd64 and linux/arm64, preventing silent regressions in native-module and runtime startup paths. Also documents how to build/publish multi-arch images for end users (including Apple Silicon).

Changes:

  • Introduces a new GitHub Actions workflow to build and verify Docker images on native amd64 + arm64 runners.
  • Adds README documentation (EN + KO) about architecture support and multi-platform buildx usage.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File Description
README.md Documents amd64/arm64 support and multi-platform Docker build guidance.
README.ko.md Korean translation of the new architecture + buildx documentation.
.github/workflows/docker.yml New CI workflow to build and verify Docker images on amd64 and arm64 runners.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread README.md
Comment on lines +559 to +567
To produce a single image that serves both architectures:

```bash
docker buildx build --platform linux/amd64,linux/arm64 -t opendocuments:latest .
```

A multi-platform build produces a manifest list rather than a single image, so
add `--push` to publish it to a registry. For local use, build one platform at a
time with `--load`.
Comment thread README.ko.md
Comment on lines +563 to +570
두 아키텍처를 모두 지원하는 단일 이미지를 만들려면:

```bash
docker buildx build --platform linux/amd64,linux/arm64 -t opendocuments:latest .
```

multi-platform 빌드는 단일 이미지가 아니라 manifest list를 생성합니다. registry에 게시하려면 `--push`를 추가하세요. 로컬에서 사용하려면 `--load`와 함께 한 번에 하나의 platform만 빌드하세요.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add ARM64 Docker support (Apple Silicon)

2 participants