Deploy: Docker

Multi-stage Dockerfile pattern for any Kumiko app. Used by all production deploys (single-VM, K3s, anywhere a container runtime exists).

Reference implementation: publicstatus/deploy/Dockerfile.

Anatomy

Build stage: Bun produces dist/ + dist-server/. Runtime: Bun-only alpine image.

ARG BUN_VERSION=1.3.14

# ---------- build: produces dist/ + dist-server/ ----------
FROM oven/bun:${BUN_VERSION}-alpine AS build
WORKDIR /app
COPY . .
RUN bun install --frozen-lockfile

WORKDIR /app
RUN bun run build

# ---------- runtime: bun + dist-server + dist + migrations ----------
FROM oven/bun:${BUN_VERSION}-alpine AS runtime
WORKDIR /app
COPY --from=build /app/dist-server ./
RUN bun install --production
COPY --from=build /app/dist ./dist
COPY --from=build /app/drizzle ./drizzle   # legacy apps; use kumiko/migrations/ when cut over

ENV KUMIKO_REPO_ROOT=/app
ENV INIT_CWD=/app

CMD ["sh", "-c", "exec bun run server.js"]

Image size: ~270 MB total (Bun + native externals + your app). Self-contained.

Run

docker run --rm \
  -e DATABASE_URL="postgresql://user:pass@host:5432/db" \
  -e REDIS_URL="redis://host:6379" \
  -p 3000:3000 \
  ghcr.io/your-org/your-app:latest

Migrate (pre-deploy step)

The image includes a bundled kumiko.js CLI. Run it as an ephemeral container before starting your app:

docker run --rm \
  -e DATABASE_URL="postgresql://user:pass@host:5432/db" \
  ghcr.io/your-org/your-app:latest \
  bun /app/kumiko.js migrate apply

Legacy apps use migrate apply. New apps (kumiko/migrations/): bun /app/kumiko.js schema apply.

Required before every deploy. Idempotent — fast no-op if nothing pending. Boot-gate refuses to start the app if the schema doesn’t match.

Build args (for CI)

docker build \
  --build-arg BUILD_VERSION="$(git describe --tags --always)" \
  --build-arg BUILD_TIME="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  -t ghcr.io/your-org/your-app:${SHA} \
  -t ghcr.io/your-org/your-app:latest \
  -f deploy/Dockerfile .

Tag both :latest and :${SHA} — :latest for rolling deploys, :${SHA} for rollbacks.

Multi-arch (arm64)

For Hetzner CAX (arm) or Apple Silicon servers, build with QEMU emulation:

docker buildx build --platform linux/arm64 --push -t ... .

In GitHub Actions: docker/setup-qemu-action@v3 + platforms: linux/arm64 on docker/build-push-action. See kumiko-platform build-image.yml for a working example.