docker-mac-arm64-elysia-vite

name: docker-mac-arm64-elysia-vite description: Docker build pitfalls on Mac arm64 (M1/M2/M3/M4) for Elysia (Bun) + Vite 8 (rolldown) projects. Covers missing libssl in oven/bun, npm optional native binding skip, package-lock.json darwin freeze, healthcheck wget absence, and frontend nginx reverse proxy setup. tags: [docker, mac, arm64, elysia, bun, vite, rolldown, prisma, nginx]

Docker on Mac arm64: Elysia + Vite Pitfalls

Hit these between 2026-06-04 building ~/www/llm-acp. Likely to repeat on any new Docker-ization of Bun + Vite 8 SPA on Apple Silicon.

Pitfall 1: Prisma 5 schema engine needs libssl

oven/bun:1.2 is Debian slim — no libssl, no wget. Prisma 5 schema engine (bunx prisma db push, migrate dev) bombs:

prisma:warn Prisma failed to detect the libssl/openssl version to use
Error: Schema engine error:

Fix (in backend/Dockerfile base stage):

FROM oven/bun:1.2 AS base
WORKDIR /app
RUN apt-get update -y && apt-get install -y openssl ca-certificates curl && rm -rf /var/lib/apt/lists/*

curl is needed too (see pitfall 2).

Pitfall 2: wget not in oven/bun:1.2

Default Compose healthcheck examples use wget. Container fails healthcheck even when Elysia is fine.

Fix in docker-compose.yml:

healthcheck:
  test: ["CMD", "curl", "-fsS", "http://localhost:PORT/api/health"]

Pitfall 3: Vite 8 + rolldown native binding not installed for linux-arm64

When you COPY package-lock.json from a Mac host into a node:20-slim (linux-x64) or arm64 image, npm preserves the lockfile's os: darwin filter for platform-specific optional deps. @rolldown/binding-linux-arm64-gnu and @rolldown/binding-linux-x64-gnu are listed as optionalDependencies and silently skipped. Build then crashes:

Error: Cannot find module '../rolldown-binding.linux-x64-gnu.node'

Similarly lightningcss (Tailwind v4 dep) has the same problem.

Fix — DON'T copy the lockfile; let container resolve fresh:

COPY package.json ./
RUN npm install --no-audit --no-fund --include=optional

Tradeoff: lockfile drift between host and container. Acceptable for SPAs. Use a platform-agnostic resolver (corepack + pnpm with --ignore-platform) if you need stricter reproducibility.

Pitfall 4: Don't --platform=linux/amd64 on Mac arm64

FROM --platform=linux/amd64 node:20-slim works for docker build via QEMU, but docker compose up will refuse to start the container:

The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8)

Fix: just use FROM node:20-slim (default arm64), and rely on pitfall 3's fix.

Pitfall 5: Prisma prisma db push --accept-data-loss is destructive

docker compose up re-runs prisma db push --accept-data-loss every time. Safe for first deploy, but on schema changes it can drop columns. Use prisma migrate deploy in production for safer rollouts.

Pitfall 6: Build context cleanliness

Backend's src/index.ts and prisma/seed.ts originally used import.meta.dir + "../.." to read ~/www/llm-acp/questions.json. Worked locally but the build context backend/ doesn't have that path. Fix: copy questions.json into backend/ and use ".." only.

Pitfall 7: Elysia 1.2 + bun build is broken in two ways (added 2026-06-05, crm-system)

When the user runs an Elysia API in a Docker image, the natural instinct is to bun build a single-file bundle for fast startup. Don't. On Elysia 1.2.x two distinct failures happen:

1. bun build --minify crashes at runtime with an internal minified variable error:

   ReferenceError: vn is not defined
       at /app/dist/index.js:413:54034
   

   Cause: Elysia's route handler uses compile?.() runtime code generation that emits references to internal variables the minifier renames inconsistently. Even --minify-whitespace alone is risky.

2. bun build --external @prisma/client (the obvious fix to keep Prisma out of the bundle) gives:

   ReferenceError: client is not defined
       at /app/dist/index.js:21172:31
   

   The --external flag breaks the bundled output's resolution of the re-exported @prisma/client namespace symbol from @crm/db.

Fix — run source directly, no bundling. COPY the entire workspace (excluding node_modules which is rebuilt) into the runtime image and start with bun run:

# runtime stage
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/apps/api ./apps/api
COPY --from=builder /app/packages/db ./packages/db
COPY --from=builder /app/packages/ai ./packages/ai
COPY --from=builder /app/packages/shared ./packages/shared
# Prisma client is hoisted to root node_modules by Bun workspaces
COPY --from=builder /app/node_modules/.prisma ./node_modules/.prisma
COPY --from=builder /app/node_modules/@prisma ./node_modules/@prisma
# ...
CMD ["bun", "run", "apps/api/src/index.ts"]

Tradeoff: image is ~200MB larger and cold start a bit slower, but it's the only stable path on Elysia 1.2.x. Revisit when Elysia 1.3+ ships a fixed bundler story.

Pitfall 8: USER bun + entrypoint script permission (added 2026-06-05, crm-system)

oven/bun:1.2 ships a bun user (uid 999). If you USER bun after COPY --chmod=755 entrypoint.sh, the entrypoint fails with:

/bin/sh: 0: cannot open /usr/local/bin/entrypoint: Permission denied

And dumb-init at the front of ENTRYPOINT just keeps respawning the container.

Fix for local deployment — run as root, add a comment for hardening later:

# Run as root for simplicity in local deployment.
# (For a more hardened setup, switch to USER bun and adjust file perms.)
# USER bun
ENTRYPOINT ["dumb-init", "/usr/local/bin/entrypoint"]

For production hardening you'd need to chown the file to bun:bun AND make /app writable.

Frontend nginx + Elysia reverse proxy

frontend/nginx.conf:

server {
    listen 80;

    location /api/ {
        proxy_pass http://backend:PORT/api/;
        # standard proxy_set_header, proxy_http_version 1.1
    }
    location / {
        try_files $uri $uri/ /index.html;  # SPA fallback
    }
    location ~* \.(js|css|png|...)$ { expires 30d; }
}

Use Docker Compose service name (backend) not localhost in proxy_pass — they share a network.

SPA fallback rewrite cycle (added 2026-06-05, crm-system)

The common try_files $uri $uri/ /index.html pattern in location / will throw a 500 on the root request with this error in the nginx container log:

[error] rewrite or internal redirection cycle while internally
redirecting to "/index.html"

Reason: when try_files falls through to /index.html, that path itself matches location / and the cycle repeats. Affects every SPA (React/Vue/Svelte) nginx setup, not just Vite.

Fix — use a named location for the fallback so the rewrite target is unambiguous:

location / {
    try_files $uri $uri/ @spa;
}
location @spa {
    root /usr/share/nginx/html;
    try_files /index.html =404;
}

@spa is a named location, never matched by URI, so no cycle.

Pitfall 9: Smoke-test API from inside the container, not the host (added 2026-06-07, crm-system)

When you need to verify a backend route end-to-end (status codes, audit log entries, validation errors), running the test from the host Mac can fail for reasons unrelated to the actual code:

• localhost:3001 may not be exposed by the container's port mapping (if docker-compose.yml doesn't publish it)
• Even with port mapping, the container may bind 0.0.0.0 while your curl hits a different host alias
• Hermes' secret-detection redacts JWTs / API keys / bearer tokens in terminal output, so TOKEN=$(curl ...) pipelines frequently produce empty tokens (the secret was wiped from the shell variable)
• Docker network IPs (e.g. 172.20.0.3) require an extra approval step in the shell for security scan

Fix — docker cp the test script into the container and run it with docker exec so the script hits localhost:3001 directly, with no host-network, no secret redaction, and no port-mapping required:

# Write your smoke test to /tmp on the HOST (one-time)
cat > /tmp/rg_smoke.ts <<'EOF'
// Use the container's runtime (bun / node) — no Python in crm-api
const BASE = "http://localhost:3001";
// ... fetch + assertions
EOF

# Copy into the container
docker cp /tmp/rg_smoke.ts crm-api:/tmp/rg_smoke.ts

# Run it
docker exec crm-api bun run /tmp/rg_smoke.ts

Container prerequisites:

• crm-api has bun and curl but not python3 — write the smoke test in TypeScript and run with bun run
• oven/bun:1.2 (crm-api base) ships node as a symlink (/usr/local/bun-node-fallback-bin/node) but bun is the preferred runtime

Tradeoffs:

• ✅ No host network
• ✅ No secret redaction
• ✅ Uses container's Prisma client / DB / Elysia exactly as production
• ⚠️ Re-deploys needed if you change the smoke test (or re-cp)
• ⚠️ crm-api image doesn't have python3 — TypeScript only

This pattern is the recommended way to verify any backend change in crm-system (and any similar oven/bun:1.2-based API container) when you can't reach it from the host.

Pitfall 10: bash 3.2.57 (macOS default) subshell PATH bug (added 2026-06-07, crm-system Day 14.7)

When writing smoke / verification shell scripts on macOS, the default bash is 3.2.57(1)-release (the last GPLv2 version shipped by Apple). It has a known quirk: $(...) command subshells do not always inherit the parent shell's PATH for non-interactive lookups, so commands like python3, curl, grep, head, git that are present at the parent may resolve to command not found inside the subshell.

Symptoms:

• Script works in interactive shell, fails the moment you wrap a command in $(...) or run it as a function called from $()
• Trace shows ++ python3 /tmp/foo.py then immediately command not found — the parent had /usr/local/bin/python3 but the subshell's bare python3 lookup fails
• Later commands head / tr / git also start failing as the subshell environment becomes degraded

Root cause — bash 3.2.57 is conservative about inheriting PATH across set -u / set -e / function boundaries, and homebrew-installed tooling at /usr/local/bin (or /opt/homebrew/bin on M1+) is NOT in the default PATH that subshells construct from /etc/profile / /etc/paths.

Fix — three layered defenses, do all three:

1. At top of script, explicitly export the canonical PATH ahead of ${PATH}:

   export PATH="/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin:${PATH}"
   

2. Use absolute paths for every command that lives outside /usr/bin / /bin (the bash default lookup dirs):

   PY="/usr/local/bin/python3"
   GREP="/usr/bin/grep"
   HEAD="/usr/bin/head"
   TR="/usr/bin/tr"
   DATE="/bin/date"
   GIT="/usr/bin/git"
   CURL="/usr/bin/curl"
   "$PY" /tmp/smoke.py ...
   "$CURL" -sS "$URL" ...
   

3. For pipes, disable pipefail locally so a single bad sub-process doesn't blow away the subshell environment:

   set +o pipefail
   DEAL_BUNDLE=$("$CURL" -sS "$URL" 2>/dev/null | "$GREP" -oE 'index-.*\.js' | "$HEAD" -1)
   set -o pipefail
   

Why it doesn't show up in simple bash -c '...' — single-line inline scripts get a clean default PATH; only the multi-line script context with set -uo pipefail and function boundaries exposes the issue.

Why it doesn't bite Linux — Linux bash 5.x and zsh inherit PATH properly. The bug is specific to bash 3.2.57 on macOS. Migrate to bash 5.x via homebrew (brew install bash and chsh -s /opt/homebrew/bin/bash) for new projects if you can.

Also relevant to: interruption-recovery smoke probes, code-review-pipeline Phase 5 merge verification, any delegate_task shell-based verifier. The 3 /tmp smoke scripts shipped on 2026-06-07 crm-system Day 14.7 (/tmp/commit-untracked-files.sh, /tmp/push-after-commit.sh, /tmp/smoke-before-merge.sh) all follow this pattern — see code-review-pipeline/templates/ for copy-pasteable templates.

Pitfall 12: Verify every Alpine package in apk add with apk search before writing the Dockerfile (added 2026-06-16, pm-system Sprint 21)

If you write RUN apk add --no-cache foo bar baz based on a blog post, a Stack Overflow answer, or even a previous project's Dockerfile, one of those packages may not exist in the current Alpine repo for the base image version you're using. The build will fail at the RUN apk add layer with:

ERROR: unable to select packages:
  catdoc (no such package):
    required by: world[catdoc]
  xls2csv (no such package):
    required by: world[xls2csv]

This exact failure happened on 2026-06-16 in pm-system Sprint 21 — Dockerfile specified apk add poppler-utils antiword xls2csv catdoc based on a plan-stage design doc. antiword exists, but catdoc and xls2csv are not in the Alpine v3.22 official repo. The first docker build failed at layer 2, 30 seconds of build time wasted, and required a hotfix commit on top of the merged Sprint 21 work.

Rule — verify before writing (5 seconds, no build needed):

# Run against the EXACT base image you're about to FROM
docker run --rm oven/bun:1-alpine sh -c "apk search 2>&1 | grep -E '^(<pkg1>-|<pkg2>-|<pkg3>-)' | head -10"

If a package isn't in the output, it's not in the repo. Find a real alternative (apk search <keyword> returns the full candidate list).

Real alternatives for the pm-system Sprint 21 case (verified against dl-cdn.alpinelinux.org v3.22 via apk search):

So the working apk add is:

RUN apk add --no-cache poppler-utils antiword wv gnumeric

Other Alpine package pitfalls worth knowing (verified same way on 2026-06-16):

• libreoffice (~1GB+) is available but overkill for headless parse — gnumeric ~30MB does .xls fine
• pandoc-cli exists (~30MB) — universal format converter, viable if you want one binary for .doc/.xls/.rtf/.odt
• wv (AbiWord) provides wvText, wvSummary, wvWare — for .doc parsing only

Why this trap is hard to spot before build:

• The packages are real and well-known (catdoc is a classic .doc reader, xls2csv is the standard Perl script). They DO exist in Debian/Ubuntu repos, in Homebrew, and in older Alpine versions (pre-v3.18).
• Plan docs / blog posts / Stack Overflow answers quote them without version-checking.
• The base image oven/bun:1-alpine ships with no man pages and no docs for what Alpine version it tracks, so you can't cat /etc/alpine-release to guess package availability.

Fix workflow when build fails on apk add (don't try to "patch around" the missing package in the existing Dockerfile line):

1. Note which package(s) failed.
2. docker run --rm <base> sh -c "apk search <keyword>" for the closest matching package name.
3. If a real alternative exists, swap it in AND update the corresponding code in src/ that calls the binary (e.g. swap catdoc command → wvText, update error messages, update tests).
4. If no alternative exists, fall back to pure JS: word-extractor (npm, .doc) or read-excel-file (npm, .xls/.xlsx) — but verify they're CVE-clean first via npm audit.
5. Always patch the retro / ADR doc with the spec error audit trail (the "Why NOT X" section), even if the fix is post-merge. Future agents reading the merged code need to know which package was swapped and why.

Connection to regression-guard: this is exactly the kind of "old assumption comes back" trap. The "Plan: use SheetJS xlsx" assumption also came from upstream docs; the Alpine apk add line was written the same way. Both were unchecked before commit. Document the fix path in retro, not just the fix itself.

Pitfall 11: "docker compose up --build fails" is often a TS error, not a Docker error (added 2026-06-10, pm-system)

When a user says "docker compose up -d --build has issues" with no error log, the failure is almost always inside the multi-stage build's frontend RUN bun run build (or npm run build) — specifically tsc -p tsconfig.app.json && vite build blowing up with TypeScript errors. The Docker daemon reports it as target frontend: failed to solve: process "/bin/sh -c bun run build" did not complete successfully: exit code: 2 — which looks like a Docker problem but is in fact a source-code TS error.

Don't ask the user to paste logs. Reproduce it locally — the build is fully local, and the error is in the captured docker compose stdout. Use terminal(background=true, notify_on_complete=true) on docker compose up -d --build 2>&1 | tail -120, then process(action='wait') to capture the tsc output.

Two recurring TS error classes in Bun + Vite + React + tsc-strict projects (seen 2026-06-10 in pm-system):

1. Call-site argument count mismatch — handler signature (e: FormEvent) => async {} invoked as onSubmit={(e) => { e.preventDefault(); handleAddTask() }} (passing 0 args to a handler that requires the event). Fix: forward the event directly — onSubmit={handleAddTask}. Don't wrap the handler just to call preventDefault() if the handler already uses the event.

2. JSX-shape vs data-shape mix in <select> options — code pattern:

   // BAD — typed as JSX.Element[], breaks typed MemberOption[] consumers
   const assigneeOptions = project?.members?.map((m) => (
     <option key={m.user.id} value={m.user.id}>{m.user.name}</option>
   )) || []
   

   When a downstream component (e.g. <AddTaskModal assigneeOptions={assigneeOptions} />) types that prop as MemberOption[] ({id, name}), TS errors: Type 'Element[]' is not assignable to type 'MemberOption[]'.

   Fix — produce data, render in consumer. Upstream returns {id, name}[], consumers .map() to <option>:

   const assigneeOptions: MemberOption[] = project?.members?.map(
     (m) => ({ id: m.user.id, name: m.user.name })
   ) || []
   // then in the consumer:
   {assigneeOptions.map((m) => (
     <option key={m.id} value={m.id}>{m.name}</option>
   ))}
   

   And explicit-annotate the const as MemberOption[] — the inferred type leaks through any props on function Component({assigneeOptions}: any) helpers in the same file, so without the annotation assigneeOptions.map((m) => ...) inside a <select> will hit Parameter 'm' implicitly has an 'any' type [7006].

Audit checklist when this happens (5 sites to check in pm-system class code):

• The producer (const assigneeOptions = ...)
• Every call site of the producer as a prop
• Every direct {assigneeOptions} JSX interpolation (used as children inside <select>)
• The MemberOption type import (must import AddTaskModal, { type MemberOption } from '../components/AddTaskModal')
• Helper functions in the same file that use any for props — they cascade the any type back to all consumers

Why this matters for Docker-debugging workflow — the user's mental model is "Docker is broken". The actual fix is a 1-line TS annotation. Capturing the build output, finding the offending line, and applying the right TS fix unblocks the whole stack (backend + frontend + db) in one cycle. If you only fix the Docker side (e.g. base image), the next tsc run will fail the same way.

Reference

Working repo: ~/www/llm-acp (CodeCommit arn:aws:codecommit:ap-east-1:646197533509:llm-acp)

• backend/Dockerfile: oven/bun multi-stage with libssl
• frontend/Dockerfile: node:20-slim multi-stage, no lockfile
• frontend/nginx.conf: /api reverse proxy to backend
• docker-compose.yml: backend + frontend + named volume for SQLite

For a full local-deployment stack (Vite SPA + Bun/Elysia API + Postgres + nginx) with copy-paste docker-compose.yml + Dockerfiles + nginx.conf + entrypoint + verification commands, see templates/full-local-stack.md (proven in ~/www/crm-system, 2026-06-05).