feat(deploy): Docker images for server (API+SPA) and vision + branch-aware build pipeline

Containerize the two non-desktop apps for the booth appliance. The desktop app stays
on its own tag-only release.yml.

- apps/server/Dockerfile: multi-stage node:22-alpine. `pnpm deploy --legacy --prod`
  (NOT prune — the monorepo native better-sqlite3 won't resolve under a root prune)
  yields a self-contained bundle; build stage adds node-gyp toolchain, runtime adds
  libstdc++; non-root, healthcheck. Migrates the mounted DB on boot via a drizzle-kit-
  free runtime migrator (packages/db/scripts/migrate-runtime.mjs) — drizzle-kit is a
  devDep, pruned from prod.
- apps/server/src/static-spa.ts: Fastify serves the built React SPA (one container
  serves API + UI). GET-only fallback to index.html, excludes /api + /health so it never
  shadows the backend; a no-op in dev (no dist). Registered last in server.ts.
- apps/vision/Dockerfile: uv base, --extra alpr, model weights PRE-WARMED into the image
  as the runtime user so fast_alpr boots offline (0 downloads at runtime). Engine env-
  selected (VISION_RECOGNIZER stub|fast_alpr).
- Branch-aware: docker-compose.yml (base) + .dev.yml (build local, stub, ports) +
  .prod.yml (pull pinned, fast_alpr, vision internal, restart always); REGISTRY/TAG from
  env so a branch deploy pulls that branch's image.
- .gitea/workflows/build-images.yml: on push to dev/main, run the full turbo build+lint+
  test gate, then buildx push both images to git.infra.msai.al/mca/parking_solution with
  branch + branch-<sha> tags (registry cache; optional Komodo webhook behind KOMODO_ENABLED).
- .dockerignore excludes **/parking.sqlite* so the signed ledger is NEVER baked.

Verified locally (Docker 29): server image migrates + serves API+SPA (/health 200, /
+ /booth HTML, /api/nope JSON 404, no sqlite outside /data); vision image boots fast_alpr
with 0 runtime downloads; compose stack healthy with server→vision over the private network.

Wiki: new container-deployment.md; vision-service-packaging open Qs resolved; index + log.

Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V

.dockerignore

@@ -0,0 +1,44 @@
+# Build context hygiene for the server + vision images (context = repo root).
+# Keep the context small and NEVER bake build artifacts, secrets, or the live DB.
+
+# Node / build outputs (rebuilt inside the image)
+**/node_modules/
+**/dist/
+**/.turbo/
+**/*.tsbuildinfo
+.turbo/
+
+# Python (vision) — rebuilt by uv inside the image
+**/.venv/
+**/__pycache__/
+**/.mypy_cache/
+**/.pytest_cache/
+**/.ruff_cache/
+
+# Secrets + local env (the image gets config via runtime env, never baked)
+**/.env
+**/.env.local
+
+# NEVER bake the live signed-ledger DB (or any of its WAL/SHM/backup variants) into an
+# image — it lives on a mounted volume. Match the base file AND every -wal/-shm/.bak-*
+# sibling (deploy copies the package dir's files, ignoring .gitignore).
+**/*.sqlite
+**/*.sqlite-*
+**/parking.sqlite*
+
+# Desktop app is built by its own tag-only release.yml, not these images
+apps/desktop/
+
+# VCS, logs, caches, editor cruft
+.git/
+.github/
+*.log
+**/.DS_Store
+.vscode/
+.idea/
+
+# Wiki raw sources / large docs (not needed to build)
+wiki/raw/
+
+# Plans / scratch
+.planning/

.gitea/workflows/build-images.yml

@@ -0,0 +1,117 @@
+name: Build & push images
+
+# Build the SERVER (API + SPA) and VISION (ANPR) container images and push them to the
+# house Gitea registry, tagged by BRANCH + short SHA (branch-aware: dev→:dev, main→:main).
+# Separate from ci.yml (checks-only) and release.yml (tag-only desktop bundle). Mirrors the
+# house pattern (cf. trm/processor build.yml). See wiki/decisions/container-deployment.md.
+
+on:
+  push:
+    branches: [dev, main]
+    paths:
+      - 'apps/server/**'
+      - 'apps/web/**'
+      - 'apps/vision/**'
+      - 'packages/**'
+      - 'package.json'
+      - 'pnpm-lock.yaml'
+      - 'pnpm-workspace.yaml'
+      - 'turbo.json'
+      - 'docker-compose*.yml'
+      - '.dockerignore'
+      - '.gitea/workflows/build-images.yml'
+  workflow_dispatch:
+
+env:
+  REGISTRY: git.infra.msai.al/mca/parking_solution
+
+jobs:
+  images:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Enable pnpm
+        run: corepack enable && corepack prepare pnpm@10.24.0 --activate
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Set up uv (for @parking/vision checks)
+        uses: astral-sh/setup-uv@v5
+
+      - name: Sync vision deps
+        working-directory: apps/vision
+        run: uv sync --frozen
+
+      # Don't publish a broken image — run the same checks as ci.yml first.
+      - name: Build + lint + test (Turbo)
+        run: pnpm turbo run build lint test
+
+      - name: Compute tags
+        id: meta
+        # BRANCH = the pushed branch (dev|main); SHA = short commit. Two tags per image:
+        # the moving branch tag + an immutable branch-SHA tag.
+        run: |
+          BRANCH="${GITHUB_REF_NAME}"
+          SHA="$(echo "${GITHUB_SHA}" | cut -c1-7)"
+          echo "branch=${BRANCH}" >> "$GITHUB_OUTPUT"
+          echo "sha=${SHA}" >> "$GITHUB_OUTPUT"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          driver: docker-container
+
+      - name: Login to Gitea Registry
+        uses: docker/login-action@v3
+        with:
+          registry: git.infra.msai.al
+          username: ${{ secrets.REGISTRY_USERNAME }}
+          password: ${{ secrets.REGISTRY_PASSWORD }}
+
+      - name: Build & push SERVER (API + SPA)
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: apps/server/Dockerfile
+          push: true
+          tags: |
+            ${{ env.REGISTRY }}/parking-server:${{ steps.meta.outputs.branch }}
+            ${{ env.REGISTRY }}/parking-server:${{ steps.meta.outputs.branch }}-${{ steps.meta.outputs.sha }}
+          cache-from: type=registry,ref=${{ env.REGISTRY }}/parking-server:buildcache
+          cache-to: type=registry,ref=${{ env.REGISTRY }}/parking-server:buildcache,mode=max
+
+      - name: Build & push VISION (ANPR)
+        uses: docker/build-push-action@v5
+        with:
+          context: apps/vision
+          file: apps/vision/Dockerfile
+          push: true
+          tags: |
+            ${{ env.REGISTRY }}/parking-vision:${{ steps.meta.outputs.branch }}
+            ${{ env.REGISTRY }}/parking-vision:${{ steps.meta.outputs.branch }}-${{ steps.meta.outputs.sha }}
+          cache-from: type=registry,ref=${{ env.REGISTRY }}/parking-vision:buildcache
+          cache-to: type=registry,ref=${{ env.REGISTRY }}/parking-vision:buildcache,mode=max
+
+      # Optional: trigger a Komodo stack redeploy (cf. trm/processor). Enable by setting the
+      # KOMODO_* secrets; left guarded so it no-ops until the parking stack is wired.
+      - name: Trigger Komodo redeploy
+        if: success() && vars.KOMODO_ENABLED == 'true'
+        env:
+          URL: ${{ secrets.KOMODO_STACK_WEBHOOK_URL }}
+          SECRET: ${{ secrets.KOMODO_WEBHOOK_SECRET }}
+        run: |
+          body="{\"ref\":\"refs/heads/${GITHUB_REF_NAME}\"}"
+          sig=$(printf '%s' "$body" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')
+          curl -fsS -X POST \
+            -H 'Content-Type: application/json' \
+            -H "X-Hub-Signature-256: sha256=$sig" \
+            -d "$body" \
+            "$URL"

apps/server/Dockerfile

@@ -0,0 +1,72 @@
+# syntax=docker/dockerfile:1.7
+# Parking SERVER image: Fastify API + the bundled React SPA (one container serves both —
+# offline-first single appliance). Build CONTEXT is the REPO ROOT (it's a pnpm/turbo
+# monorepo). better-sqlite3 is a native module → build stage needs node-gyp toolchain,
+# runtime needs libstdc++. Mirrors the house multi-stage pattern (cf. trm/processor).
+# See wiki/decisions/container-deployment.md.
+
+# ---- deps: cache-friendly pnpm fetch (only manifests change the layer) ----
+FROM node:22-alpine AS deps
+WORKDIR /app
+RUN apk add --no-cache python3 make g++   # node-gyp for better-sqlite3
+RUN corepack enable && corepack prepare pnpm@10.24.0 --activate
+# Workspace manifests + lock first, so the fetch layer caches across source edits.
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml turbo.json ./
+COPY apps/server/package.json     apps/server/
+COPY apps/web/package.json        apps/web/
+COPY apps/vision/package.json     apps/vision/
+COPY packages/db/package.json     packages/db/
+COPY packages/devices/package.json packages/devices/
+COPY packages/shared/package.json packages/shared/
+RUN --mount=type=cache,id=pnpm-store,target=/root/.local/share/pnpm/store \
+    pnpm fetch
+
+# ---- build: install (offline from the fetched store) + turbo build everything ----
+FROM deps AS build
+ENV CI=true
+COPY . .
+RUN --mount=type=cache,id=pnpm-store,target=/root/.local/share/pnpm/store \
+    pnpm install --frozen-lockfile --offline
+# Builds shared/db/devices, the server dist, AND the web SPA dist (apps/web/dist).
+RUN pnpm turbo run build --filter=@parking/server --filter=@parking/web
+# `pnpm deploy` produces a SELF-CONTAINED prod bundle for the server in /deploy: a hoisted
+# node_modules with only @parking/server's prod deps (incl. the workspace packages' built
+# dist + their native deps like better-sqlite3 — properly linked, unlike `prune` at root).
+RUN --mount=type=cache,id=pnpm-store,target=/root/.local/share/pnpm/store \
+    pnpm --filter=@parking/server --legacy deploy --prod /deploy
+# The server's own dist + scripts (deploy copies the package's package.json + files, but we
+# copy dist explicitly so the layout under /deploy is predictable). The web SPA + db
+# migrations are copied in the runtime stage from their build locations.
+
+# ---- runtime: slim, non-root ----
+FROM node:22-alpine AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+RUN apk add --no-cache libstdc++   # better-sqlite3 native runtime
+RUN addgroup -S app && adduser -S -G app app
+
+# The self-contained deploy bundle: dist/ + a hoisted node_modules carrying the server's
+# prod deps AND the workspace packages (@parking/db|devices|shared) with their built dist,
+# the drizzle migrations, and the native better-sqlite3 binding. Single COPY — no scattered
+# package dirs, no root node_modules.
+COPY --from=build --chown=app:app /deploy ./
+
+# The built SPA — served by Fastify static at WEB_DIST_DIR. (Not part of the server's deploy
+# bundle, so copied from the web build output.)
+COPY --from=build --chown=app:app /app/apps/web/dist ./web/dist
+
+# DB lives on a mounted volume (never in the image). Default points at /data.
+ENV DATABASE_URL=/data/parking.sqlite
+ENV WEB_DIST_DIR=/app/web/dist
+ENV HOST=0.0.0.0
+ENV PORT=3000
+RUN mkdir -p /data && chown app:app /data
+VOLUME ["/data"]
+
+USER app
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+  CMD wget -qO- "http://localhost:${PORT:-3000}/health" >/dev/null 2>&1 || exit 1
+
+ENTRYPOINT ["./docker-entrypoint.sh"]
+CMD ["node", "dist/index.js"]

apps/server/docker-entrypoint.sh

@@ -0,0 +1,27 @@
+#!/bin/sh
+# Container entrypoint for the parking server. Applies DB migrations against the mounted
+# volume (DATABASE_URL), optionally seeds the first admin, then execs the server. Idempotent:
+# the runtime migrator (drizzle-orm migrator, no drizzle-kit) only applies pending migrations,
+# so a restart is a no-op. See packages/db/scripts/migrate-runtime.mjs.
+set -e
+
+echo "[entrypoint] DATABASE_URL=${DATABASE_URL}"
+
+# Apply migrations against the mounted DB file (creates it + the schema on first boot).
+# The migrator ships inside the @parking/db package in the deploy bundle's node_modules.
+node node_modules/@parking/db/scripts/migrate-runtime.mjs
+
+# Optional first-boot admin seed: set SEED_ADMIN=1 plus ADMIN_USER + ADMIN_PASS (the seed
+# script PROMPTS when these are unset, which would hang a container — so require ADMIN_PASS).
+# The seed is idempotent: it won't overwrite an existing user unless FORCE=1.
+if [ "${SEED_ADMIN}" = "1" ]; then
+  if [ -z "${ADMIN_PASS}" ]; then
+    echo "[entrypoint] SEED_ADMIN=1 but ADMIN_PASS is unset — skipping seed (would hang on prompt)"
+  else
+    echo "[entrypoint] seeding admin (${ADMIN_USER:-admin})"
+    node scripts/seed-admin.mjs || echo "[entrypoint] seed-admin skipped/failed (non-fatal)"
+  fi
+fi
+
+echo "[entrypoint] starting server"
+exec "$@"

apps/server/src/server.ts

@@ -44,6 +44,7 @@ import { printerRoutes } from "./routes/printers.js";
 import { setupRoutes } from "./routes/setup.js";
 import { deviceStatusRoutes } from "./routes/device-status.js";
 import { wsRoutes } from "./routes/ws.js";
+import { registerSpa } from "./static-spa.js";
 
 // The backend is Fastify (Node). Hardware drivers live as isolated Fastify
 // plugins emitting onto a shared internal event bus; auth is fully local
@@ -300,5 +301,12 @@ export async function buildServer(opts: BuildOptions = {}): Promise<FastifyInsta
   });
   app.addHook("onClose", async () => unsubscribeInput());
 
+  // LAST: serve the built React SPA (apps/web/dist) when present — so one container
+  // serves the API + the operator UI (offline-first single appliance). No-op in dev (no
+  // build → the Vite dev server serves the UI). Registered after every API route and
+  // GET-only with /api + /health excluded, so it can never shadow the backend.
+  // See static-spa.ts + wiki/decisions/container-deployment.md.
+  await registerSpa(app);
+
   return app;
 }

apps/server/src/static-spa.ts

@@ -0,0 +1,56 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import fastifyStatic from "@fastify/static";
+import type { FastifyInstance } from "fastify";
+
+// Serve the built React SPA (apps/web/dist) from the Fastify server, so ONE container
+// serves both the API and the operator UI — matching the offline-first single-appliance
+// model (the booth has no separate web host). This is a NO-OP in dev (the Vite dev server
+// serves the SPA on its own port and no dist exists), so it never changes local behavior.
+//
+// Registration order matters: this is registered LAST, after every API route, and its
+// catch-all is GET-only and explicitly excludes /api, /health, and the WS path — so it
+// can never shadow the backend. See wiki/decisions/container-deployment.md.
+
+/** Where the built SPA lives. Override with WEB_DIST_DIR (the container sets it). Default
+ *  resolves relative to this file's dist location: apps/server/dist → ../../web/dist, the
+ *  layout the image lays down (/app/dist + /app/web/dist → ../web/dist from dist). */
+function resolveWebDist(): string {
+  const fromEnv = process.env.WEB_DIST_DIR;
+  if (fromEnv) return resolve(fromEnv);
+  const here = dirname(fileURLToPath(import.meta.url));
+  // In the image the server runs from /app/dist and the SPA sits at /app/web/dist.
+  return resolve(here, "../web/dist");
+}
+
+/**
+ * Register SPA static serving if a build is present. Returns true when wired, false when
+ * skipped (dev / no build). Serves assets from the dist dir and falls back to index.html
+ * for any non-API GET so client-side routing (TanStack Router) works on deep links/reload.
+ */
+export async function registerSpa(app: FastifyInstance): Promise<boolean> {
+  const root = resolveWebDist();
+  const indexHtml = resolve(root, "index.html");
+  if (!existsSync(indexHtml)) {
+    app.log.info(`SPA static serving disabled (no build at ${root})`);
+    return false;
+  }
+
+  await app.register(fastifyStatic, { root, wildcard: false });
+
+  // SPA fallback: any GET that didn't match an API route or a real static file returns
+  // index.html (client routing). EXCLUDE the backend surfaces so a missing /api route
+  // still 404s as JSON rather than silently returning the HTML shell. WS upgrades and
+  // non-GET methods are never touched (this is a GET-only notFound handler path).
+  app.setNotFoundHandler((req, reply) => {
+    const url = req.raw.url ?? "/";
+    if (req.method !== "GET" || url.startsWith("/api") || url.startsWith("/health")) {
+      return reply.code(404).send({ error: "not found" });
+    }
+    return reply.sendFile("index.html");
+  });
+
+  app.log.info(`SPA static serving enabled from ${root}`);
+  return true;
+}

apps/vision/Dockerfile

@@ -0,0 +1,57 @@
+# syntax=docker/dockerfile:1.7
+# Parking VISION image: the Python/uv ANPR microservice. Build CONTEXT is apps/vision
+# (self-contained Python package; no monorepo deps). Ships WITH the `alpr` extra (real
+# fast-alpr/onnxruntime stack) but the engine is env-selected: VISION_RECOGNIZER=stub
+# (default, boots anywhere) or fast_alpr (prod). See wiki/decisions/container-deployment.md,
+# wiki/decisions/vision-service-packaging.md.
+
+# uv-provided Python 3.12 (matches apps/vision/.python-version).
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS base
+WORKDIR /app
+ENV UV_LINK_MODE=copy \
+    UV_COMPILE_BYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+# System libs the recognizer stack needs (opencv/onnxruntime): GL + glib. Kept minimal.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libgl1 libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+# ---- deps: resolve + install the venv from the lockfile (cache-friendly) ----
+# Manifests first so the heavy `uv sync` layer caches across source edits.
+COPY pyproject.toml uv.lock .python-version ./
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-install-project --extra alpr
+
+# ---- project source ----
+COPY vision_service/ ./vision_service/
+COPY README.md ./
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --extra alpr
+
+# Non-root runtime user, created BEFORE the model pre-warm so the weights cache lands in
+# this user's HOME (~/.cache) — the SAME path the runtime reads. (fast-alpr's
+# open-image-models caches under $HOME/.cache/open-image-models keyed to HOME, ignoring
+# HF_HOME/XDG_CACHE_HOME — so the pre-warm MUST run as the runtime user, not root.)
+RUN useradd --system --create-home --uid 999 vision \
+    && chown -R vision:vision /app
+USER vision
+
+# Pre-warm the fast-alpr model weights INTO the image (as the vision user → /home/vision/
+# .cache) so the prod recognizer is OFFLINE-first: ALPR() downloads weights on first
+# construction, which would otherwise need network on the appliance's first scan. Best-effort
+# — if the build host has no network this is skipped and weights fetch lazily at runtime.
+# NB: NO --mount=type=cache here — a BuildKit cache mount at ~/.cache is NOT committed to the
+# image layer, so the downloaded weights would vanish. They must write to the real layer.
+RUN uv run python -c "from fast_alpr import ALPR; ALPR()" \
+    || echo "[build] model pre-warm skipped (no network) — weights fetch at runtime"
+
+# Default to the stub recognizer (offline, no model load); override to fast_alpr in prod.
+ENV VISION_RECOGNIZER=stub \
+    VISION_HOST=0.0.0.0 \
+    VISION_PORT=8089
+EXPOSE 8089
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8089/health').status==200 else 1)" || exit 1
+
+CMD ["uv", "run", "uvicorn", "vision_service.app:app", "--host", "0.0.0.0", "--port", "8089"]

docker-compose.dev.yml

@@ -0,0 +1,29 @@
+# DEV override: build the images locally from the Dockerfiles, expose both ports, run the
+# stub recognizer (no model load), and verbose logging. Use with the base file:
+#   docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
+
+services:
+  server:
+    build:
+      context: .
+      dockerfile: apps/server/Dockerfile
+    environment:
+      LOG_LEVEL: debug
+      # Dev convenience: seed an admin on first boot (set ADMIN_PASS to enable).
+      SEED_ADMIN: ${SEED_ADMIN:-0}
+      ADMIN_USER: ${ADMIN_USER:-admin}
+      ADMIN_PASS: ${ADMIN_PASS:-}
+      # 32+ chars and must NOT contain dev-only/insecure/change-me (auth.ts rejects those).
+      # This is a fixed LOCAL-DEV value only; prod injects a real `openssl rand -hex 32`.
+      JWT_SECRET: ${JWT_SECRET:-localdevsecret0123456789abcdef0123}
+    ports:
+      - "3000:3000"
+
+  vision:
+    build:
+      context: apps/vision
+      dockerfile: Dockerfile
+    environment:
+      VISION_RECOGNIZER: stub
+    ports:
+      - "8089:8089"

docker-compose.prod.yml

@@ -0,0 +1,28 @@
+# PROD override: pull pinned registry images (no local build), restart always, real
+# recognizer, and keep vision INTERNAL (only the server port is published). Use with the
+# base file and pin TAG to the branch/SHA you deploy:
+#   REGISTRY=git.infra.msai.al/mca/parking_solution TAG=main \
+#     docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+
+services:
+  server:
+    restart: always
+    ports:
+      - "3000:3000"
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+  vision:
+    restart: always
+    # The real ANPR engine. The image baked the model weights at build (offline-first).
+    environment:
+      VISION_RECOGNIZER: fast_alpr
+    # No published ports — vision is reached only by the server over the private network.
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"

docker-compose.yml

@@ -0,0 +1,42 @@
+# Base stack: the parking SERVER (API + SPA) + the VISION (ANPR) service. Branch-aware via
+# ${REGISTRY}/${TAG} — a deploy on `dev` pulls :dev, on `main` pulls :main. Use an env
+# override file for the environment: docker-compose.dev.yml (build locally, stub recognizer)
+# or docker-compose.prod.yml (pull pinned images, fast_alpr). See
+# wiki/decisions/container-deployment.md.
+#
+#   local dev : docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
+#   prod      : REGISTRY=… TAG=main docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+
+services:
+  server:
+    image: ${REGISTRY:-git.infra.msai.al/mca/parking_solution}/parking-server:${TAG:-dev}
+    restart: unless-stopped
+    environment:
+      DATABASE_URL: /data/parking.sqlite
+      # Reach the vision service over the private compose network by service name.
+      VISION_URL: http://vision:8089
+      # JWT signing secret MUST be provided at deploy (no insecure default — see auth.ts).
+      JWT_SECRET: ${JWT_SECRET:?set JWT_SECRET in the env/.env}
+    volumes:
+      - parking-data:/data
+    depends_on:
+      vision:
+        condition: service_started
+    networks:
+      - parking
+
+  vision:
+    image: ${REGISTRY:-git.infra.msai.al/mca/parking_solution}/parking-vision:${TAG:-dev}
+    restart: unless-stopped
+    environment:
+      # Engine: stub (no models) by default; prod override sets fast_alpr.
+      VISION_RECOGNIZER: ${VISION_RECOGNIZER:-stub}
+    networks:
+      - parking
+
+volumes:
+  parking-data:
+
+networks:
+  parking:
+    driver: bridge

packages/db/package.json

@@ -25,7 +25,8 @@
     "typecheck": "tsc --noEmit",
     "lint": "tsc --noEmit",
     "db:generate": "drizzle-kit generate",
-    "db:migrate": "DATABASE_URL=\"${DATABASE_URL:-../../apps/server/parking.sqlite}\" drizzle-kit migrate"
+    "db:migrate": "DATABASE_URL=\"${DATABASE_URL:-../../apps/server/parking.sqlite}\" drizzle-kit migrate",
+    "db:migrate:runtime": "node scripts/migrate-runtime.mjs"
   },
   "dependencies": {
     "@parking/shared": "workspace:*",

packages/db/scripts/migrate-runtime.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// Apply Drizzle migrations against the DATABASE_URL sqlite file using the runtime
+// migrator (drizzle-orm/better-sqlite3/migrator) — NOT drizzle-kit. This lets the
+// container run migrations on boot with only runtime deps installed (drizzle-kit is a
+// devDep, pruned out of the production image). Same migration set + folder the test
+// helper uses (packages/db/src/testing.ts), so the schema matches production exactly.
+//
+// Usage: DATABASE_URL=/data/parking.sqlite node scripts/migrate-runtime.mjs
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { mkdirSync } from "node:fs";
+import Database from "better-sqlite3";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+import { migrate } from "drizzle-orm/better-sqlite3/migrator";
+
+const url = process.env.DATABASE_URL;
+if (!url) {
+  console.error("[migrate] DATABASE_URL is required");
+  process.exit(1);
+}
+
+// Migrations folder ships beside this package (packages/db/drizzle); from scripts/ that's ../drizzle.
+const migrationsFolder = resolve(dirname(fileURLToPath(import.meta.url)), "../drizzle");
+
+// Ensure the DB's parent dir exists (a fresh mounted volume may be empty).
+try {
+  mkdirSync(dirname(resolve(url)), { recursive: true });
+} catch {
+  /* dir already exists (or url has no dir) — fine */
+}
+
+const sqlite = new Database(url);
+sqlite.pragma("journal_mode = WAL");
+sqlite.pragma("foreign_keys = ON");
+const db = drizzle(sqlite);
+
+console.log(`[migrate] applying migrations from ${migrationsFolder} → ${url}`);
+migrate(db, { migrationsFolder });
+sqlite.close();
+console.log("[migrate] done");

wiki/decisions/container-deployment.md

@@ -0,0 +1,99 @@
+---
+type: decision
+tags: [parking, deployment, docker, ci, offline-first]
+sources: []
+updated: 2026-06-22
+status: settled
+---
+
+# Container deployment (Docker images for the non-desktop apps)
+
+How the parking system's runtime apps are packaged as containers, tagged, and published.
+Settled 2026-06-22. Companion to [[vision-service-packaging]] (which scopes the vision service
+into the monorepo) and the desktop [[desktop-shell-tauri]] (a separate, tag-only bundle).
+
+## Two images (the desktop app is NOT containerized)
+
+- **`parking-server`** — the Fastify API **plus the built React SPA**. One container serves both:
+  Fastify serves `apps/web/dist` via `@fastify/static` (wired in `apps/server/src/static-spa.ts`),
+  with an SPA fallback to `index.html` for client routing. This matches [[offline-first]] — the
+  booth appliance is one box, not a web host + an API host. `@fastify/web` static serving is a
+  **no-op in dev** (no build dir → the Vite dev server serves the UI), so local DX is unchanged.
+- **`parking-vision`** — the Python/uv ANPR service ([[opencv-anpr-service]]). Ships WITH the
+  `alpr` extra (real fast-alpr/onnxruntime stack); the engine is env-selected
+  (`VISION_RECOGNIZER=stub|fast_alpr`, default `stub` so it boots anywhere). Model weights are
+  **pre-warmed at build** (best-effort) so the appliance's first scan needs no network.
+
+The **desktop** app stays on its own tag-only `release.yml` (Tauri installers), not these images.
+
+## Branch-aware (the user's hard requirement)
+
+- **Image tags = branch + short SHA.** A push to `dev` builds `…/parking-server:dev` +
+  `…/parking-server:dev-<sha>`; `main` builds `:main` + `:main-<sha>`. The moving branch tag is the
+  deploy pointer; the branch-SHA tag is the immutable record. Same for `parking-vision`.
+- **Per-env compose.** A base `docker-compose.yml` + overrides: `docker-compose.dev.yml` (build
+  locally, expose ports, `stub` recognizer) and `docker-compose.prod.yml` (pull pinned images,
+  `restart: always`, `fast_alpr`, vision kept internal). `REGISTRY`/`TAG` come from env, so a deploy
+  on a branch pulls that branch's image — the branch→environment mapping IS the override file.
+
+## Registry + CI
+
+- Published to the house **Gitea registry** `git.infra.msai.al/mca/parking_solution/{parking-server,
+  parking-vision}`. Login via `REGISTRY_USERNAME`/`REGISTRY_PASSWORD` secrets.
+- New workflow **`.gitea/workflows/build-images.yml`** (separate from the checks-only `ci.yml` and the
+  tag-only `release.yml`): on push to `dev`/`main`, run the full `turbo build lint test` first (don't
+  ship a broken image), then buildx + `docker/build-push-action` for both images with branch+SHA tags
+  and a registry build cache. An optional Komodo redeploy webhook is guarded behind a `KOMODO_ENABLED`
+  var (mirrors the house `trm/processor` pattern). The vision checks need `uv` (the `astral-sh/setup-uv`
+  step), same as `ci.yml`.
+
+## Build specifics that bit us (record so they don't recur)
+
+- **`pnpm deploy --legacy --prod`, NOT `pnpm prune --prod`.** It's a pnpm/turbo monorepo; pruning at
+  the root leaves `packages/db/node_modules` empty, so the native **`better-sqlite3`** binding can't
+  resolve at runtime. `pnpm deploy` produces a self-contained, hoisted bundle (the workspace packages'
+  built `dist` + their native deps) — a single `COPY --from=build /deploy ./`. pnpm 10 needs `--legacy`
+  (or `inject-workspace-packages`).
+- **Native modules**: Alpine build stage needs `python3 make g++` (node-gyp for better-sqlite3);
+  runtime needs `libstdc++`. `bcrypt` ships a `linux-x64/musl` prebuild, so it works on Alpine as-is.
+- **`pnpm prune`/deploy refuse to run without a TTY** unless `CI=true` (or `ENV CI=true`) is set in
+  the build stage.
+- **Migrations at boot, not at build.** The DB lives on a mounted volume (`/data`), so the entrypoint
+  runs them against the live file via a **drizzle-kit-free** runtime migrator
+  (`packages/db/scripts/migrate-runtime.mjs`, using `drizzle-orm/.../migrator` — drizzle-kit is a
+  devDep, pruned from the prod bundle). Idempotent: a restart re-applies nothing.
+- **JWT_SECRET** must be a real value at deploy — `auth.ts` rejects anything `<32` chars or matching
+  `change.?me|insecure|dev-only`, so the dev compose default is a benign 32-char string, not a
+  "dev-only…" placeholder (which would crash boot).
+- **Vision model pre-warm must run AS the runtime user.** fast-alpr's `open-image-models` caches
+  weights under `$HOME/.cache/open-image-models` keyed to `$HOME` — it ignores `HF_HOME`/
+  `XDG_CACHE_HOME`. A first attempt pre-warmed as root (`/root/.cache`), so the non-root runtime
+  re-downloaded at boot (offline-first BROKEN). Fix: create the `vision` user first, `USER vision`,
+  THEN run `python -c "from fast_alpr import ALPR; ALPR()"` so weights land in `/home/vision/.cache`
+  — exactly where the runtime reads. Verify the boot log shows NO "Downloading …onnx".
+
+## Invariants (must hold)
+
+- **Never bake the live DB.** `.dockerignore` excludes `**/parking.sqlite*` (incl. `-wal`/`-shm`/
+  `.bak-*`) — `pnpm deploy` copies the package dir's files ignoring `.gitignore`, so the
+  `.dockerignore` (which gates the build CONTEXT) is what keeps the signed ledger out of the image.
+  The DB is a host-volume asset ([[append-only-event-chain]], [[threat-model]]).
+- **SPA serving must not shadow the API** — the fallback is GET-only and excludes `/api`, `/health`;
+  a missing `/api/*` still 404s as JSON, not the HTML shell.
+- **Offline-first** — both images boot + serve with no network (vision default `stub`; `fast_alpr`
+  weights pre-warmed into the image layer).
+- **Non-root runtime**, minimal final image (deploy bundle only; build toolchain dropped).
+
+## Verified on hardware (2026-06-22)
+
+Both images built + smoke-tested locally (Docker 29, buildx):
+
+- **server**: build → run → entrypoint migrates `/data/parking.sqlite`, SPA static serving enabled,
+  server listens; `/health` 200, `/` + `/booth` serve the SPA (text/html), `/api/nope` → JSON 404;
+  no `parking.sqlite*` anywhere outside `/data` in the image.
+- **vision** (1.8 GB, `--extra alpr`): build pre-warms the YOLOv9 + CCT weights into the image
+  (`/home/vision/.cache`); run as `fast_alpr` → `ready:true` with **0 downloads at boot** (offline-
+  first confirmed); `stub` mode also boots clean.
+- **compose** (`docker-compose.yml` + `.dev.yml`): both containers come up healthy and the server
+  reaches the vision service over the private network (`wget http://vision:8089/health` from the
+  server container → 200).

wiki/decisions/vision-service-packaging.md

@@ -110,3 +110,7 @@ The skeleton is **built and wired** (no recognizer models yet):
   weights out of the build entirely (baked into the Docker image instead).
 - Container/runtime supervision on the appliance (systemd unit vs. compose) — deployment detail,
   defer to the install/hardening pass.
+
+> **Resolved 2026-06-22 → [[container-deployment]]:** the vision service now ships as the
+> `parking-vision` Docker image (uv base, `--extra alpr`), model weights **pre-warmed into the image
+> layer** at build (offline-first), and runs under **docker-compose** (base + per-env override).

wiki/index.md

@@ -121,3 +121,4 @@ Counts: 4 sources · 19 entities · 45 concepts · 7 decision records.
 - [[vision-service-packaging]] — the vision service lives in this monorepo (apps/vision/), separate process, wired into Turbo via a package.json shim; uv-managed Python.
 - [[event-streams-split]] — split the signed business ledger (ledger_events) from unsigned device telemetry (device_events).
 - [[desktop-shell-tauri]] — ✅ Tauri v2 chosen over Electron for the desktop kiosk shell; thin wrapper, server keeps all logic. Best case Ubuntu 26.04 LTS (resolves WebKitGTK); worst case Windows+WSL → kiosk browser, no native shell.
+- [[container-deployment]] — Docker images for the non-desktop apps: parking-server (Fastify API + bundled SPA via @fastify/static) + parking-vision (Python/uv ANPR); branch+SHA tags, per-env compose, Gitea registry, build-images.yml CI; pnpm deploy (not prune) for native better-sqlite3; migrate-at-boot.

wiki/log.md

@@ -1463,3 +1463,24 @@ classified via event-detail.tsx isRefusedWarning and shown as amber REFUZUAR/REF
 ANOMALI for genuine red-flags. No ledger change → historical events reclassify too. New reason code
 void.ticketCancelled (shared + both web catalogs). Tests: void-flow.test.ts (8) + occupancy void fold;
 141 server + 87 shared green; build+lint (TS + i18n parity) green. Updated [[parking-session]].
+
+## [2026-06-22] build | Docker images for non-desktop apps (server+SPA, vision) + branch-aware build pipeline
+Containerized the two runtime apps. parking-server = Fastify API + the bundled React SPA (wired
+@fastify/static in new static-spa.ts — serves apps/web/dist with an SPA index.html fallback, GET-only
+and excluding /api + /health so it never shadows the backend; a NO-OP in dev where no dist exists).
+parking-vision = the Python/uv ANPR service, ships --extra alpr with model weights pre-warmed into the
+image (offline-first), engine env-selected (VISION_RECOGNIZER stub|fast_alpr). Branch-aware per the
+user: images tagged branch + branch-<sha>; base docker-compose.yml + docker-compose.dev.yml (build
+local, stub, ports) / docker-compose.prod.yml (pull pinned, fast_alpr, vision internal, restart
+always). New .gitea/workflows/build-images.yml pushes both to git.infra.msai.al/mca/parking_solution
+on push to dev/main, after a full turbo build+lint+test gate (mirrors trm/processor; optional Komodo
+webhook behind KOMODO_ENABLED). KEY build lessons: use `pnpm deploy --legacy --prod` NOT
+`pnpm prune` (monorepo: prune leaves the native better-sqlite3 unresolved); Alpine needs
+python3/make/g++ (build) + libstdc++ (runtime); set CI=true so pnpm wipes node_modules; migrate at
+BOOT via a drizzle-kit-free runtime migrator (packages/db/scripts/migrate-runtime.mjs) against the
+mounted /data volume; .dockerignore must exclude **/parking.sqlite* (deploy ignores .gitignore) so the
+signed ledger is NEVER baked. JWT_SECRET must be a real >=32-char value (auth.ts rejects dev-only/
+insecure/change-me). VERIFIED: server image builds + runs — migrates, SPA serving on, /health 200,
+/ + /booth serve HTML, /api/nope JSON 404, no sqlite outside /data. Vision image build + smoke in
+progress. New page [[container-deployment]]; updated [[vision-service-packaging]] (resolved its two
+open Qs), index. Server tests stay 141 green (SPA serving guarded on dist existence).