kampodine 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 0.2.1 — 2026-10-07
+
+Docs, hygiene, and deploy hardening.
+
+- Global-audience README: rewritten so it reads clean outside the
+  original deployment (no service names, timings, or internal history)
+- Removed origin-specific defaults that leaked a real host: the deploy
+  target and Host-header defaults are now placeholders — set `ESPELLAR_HOST`
+  and `PROXY_HOST` / `APP_HOST_HEADER` explicitly (they were env overrides
+  before and still are)
+- `deploy`: `--dockerfile <path>` for alternative image recipes (e.g. a Go
+  cutover image, built with `GIT_SHA` instead of `VITE_BUILD_ID`); the
+  health probe now runs on the VM host (busybox wget) so scratch/Go images
+  without a shell probe cleanly
+- Script/test comments: tightened wording across the shipped scripts,
+  keeping the technical rationale
+- Fixed standalone-repo test paths (two vm-prepare suites still resolved the
+  old monorepo layout); repo gained `.gitignore` + `package-lock.json`
+
+## 0.2.0 — 2026-10-07
+
+- `bluegreen` — reserved-IP blue/green pairs on OCI:
+  `status|init|provision|flip|rollback`; zero-DNS flips, ACME-first
+  cutover, health-gated with automatic rollback; a guest anchor watcher is
+  shipped by `vm-prepare`
+- `vm-prepare` — sshd-hardening self-heal for fresh VMs, busybox-wget
+  probes (the golden image ships no curl), anchor watcher install
+- `image-import` — every `oci` call honors `OCI_PROFILE`
+
+## 0.1.0 — 2026-10-05
+
+- First release: registry-free stream deploy (`podman save | ssh podman
+  load`) with sha-verified health gate and instant rollback, kamal-proxy
+  TLS/ACME registration, OpenRC golden-image pipeline, `migrate` (sqlite
+  migrations over SSH), OCI image-import path

package/README.md

@@ -49,22 +49,19 @@ kampodine deploy:
   existing build; `--rollback [sha]` is an instant image-tag rollback (the
   previous image stays on the VM for exactly this)
 - **`kampodine bluegreen status|init|provision|flip|rollback`** — reserved
-  public IP management for a two-instance blue/green pair (zero DNS change,
-  health-gated flips, auto-rollback). **0.2.0: live-proven end-to-end** —
-  provision via platform-launch + golden-qcow2 disk injection (~9 min to a
-  booting Alpine A1; OCI custom-image import is BIOS-pinned and A1-rejects),
-  a guest **anchor watcher** shipped by `vm-prepare` (add-only, inert until
-  a flip writes `/etc/esellar/anchor.conf`), the **ACME-first flip**
-  (~27 s: anchor → OCI assign → cert for the reserved-IP hostname →
-  served-sha verify) with a ~6 s rollback, and a strict inject gate
-  (release must match Alpine `3.x`; reboot failures die loudly)
-- **`kampodine vm-prepare`** — first-run bootstrap of a bare Alpine host
-  (0.2.0: sshd-hardening self-heal — fresh VMs pass unattended; busybox-wget
-  probes — the golden image ships no curl; ships `esellar-anchor`)
-- **`kampodine image-import`** — golden qcow2 → OCI custom image (0.2.0:
-  every `oci` call honors `OCI_PROFILE`; note A1 rejects imported images —
-  use `bluegreen provision` for Ampere targets)
-- **`kampodine migrate`** — sqlite migrations overSSH
+  public IP management for a two-instance blue/green pair on OCI: zero DNS
+  change, health-gated flips with an ACME-first cutover (reserved IP assigned
+  → cert issued for its hostname → served sha verified) and automatic
+  rollback. A guest **anchor watcher** installed by `vm-prepare` holds the
+  flip's IP half — add-only and inert until a flip writes its anchor config.
+- **`kampodine vm-prepare`** — first-run bootstrap of a bare Alpine host:
+  sshd hardening (fresh VMs pass unattended), busybox-wget health probes (the
+  golden image ships no curl), the blue-green anchor watcher, the podman
+  stack, and OpenRC `supervise-daemon` units for app + kamal-proxy
+- **`kampodine image-import`** — golden qcow2 → OCI custom image. Caveat:
+  imported custom images boot BIOS and are rejected by Ampere (A1) shapes —
+  use `bluegreen provision` for ARM targets
+- **`kampodine migrate`** — sqlite migrations over SSH
 
 ## Kamal parity
 
@@ -133,7 +130,7 @@ tunnel (`ssh -R 5000:127.0.0.1:5000`).
 
 Rule of thumb: one VM and no existing registry → stream. Multiple targets,
 CI-driven deploys, or a registry you already run → mirror. Registry-path
-automation is on the roadmap; v0.1.0 ships the stream.
+automation is on the roadmap; today the stream is the automated path.
 
 ## Prerequisites
 
@@ -147,10 +144,11 @@ ssh as root, with kamal-proxy running.
 
 ## Status
 
-v0.1.0 — kampodine deploys a production service today. Some defaults are
-still coupled to the deployment it grew out of (env schema path, service and
-container names, deploy-host env) — genericizing them is the top roadmap
-item. Founding doc + checklist: [`kampodine.md`](./kampodine.md).
+Proven on production deployments (v0.2.x). Defaults are still opinionated —
+service/container names, env-file path, deploy-host env — and genericizing
+them is the top roadmap item. Design reference + roadmap:
+[`kampodine.md`](./kampodine.md). Release history:
+[CHANGELOG.md](./CHANGELOG.md).
 
 ## License
 

package/kampodine.md

@@ -70,22 +70,21 @@ no registry, no tunnel, no docker, no systemd — SSH + podman only.
       instance exists
 - [x] sqlite migration runner (`migrate`)
 - [x] OCI image import path (`image-import`)
+- [x] npm package — bin `kampodine`, scripts shipped in-package, published on
+      npm, with package tests (script contract gates: `bash -n` + shellcheck
+      over every script; cli dispatch contract: help/version/exit codes/bin
+      integrity)
 
-**In flight:**
-- [ ] npm package scaffold — bin `kampodine`, scripts shipped in-package
+**In progress:**
 - [ ] reference sweep (docs → kampodine invocations)
 
-**Todo:**
-- [ ] package tests — script contract gates (bash -n + shellcheck over every
-      script), cli dispatch contract (help/version/exit codes/bin integrity)
-- [ ] end-to-end verification: one real deploy through the CLI (zero-change
-      restream of the live image, full pipeline verify)
-- [ ] `kampodine status` — live served sha + pair view in one command
-- [ ] registry-path automation (mirror mode: push to any OCI registry,
-      VM-side pull, same health-gate/cutover tail)
-- [ ] genericize origin-coupled defaults (env schema path, service/container
-      names, deploy-host env) into config
-- [ ] npm publish
+## Roadmap
+
+- `kampodine status` — live served sha + pair view in one command
+- registry-path automation (mirror mode: push to any OCI registry,
+  VM-side pull, same health-gate/cutover tail)
+- genericized defaults (env schema path, service/container names,
+  deploy-host env) driven by config
 
 ## Non-goals
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kampodine",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Kamal-style deploys for Alpine + Podman hosts, built on kamal-proxy",
   "license": "AGPL-3.0",
   "type": "module",
@@ -14,7 +14,8 @@
   "files": [
     "cli.js",
     "scripts/",
-    "kampodine.md"
+    "kampodine.md",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=20"

package/scripts/bluegreen.sh

@@ -1,13 +1,14 @@
 #!/usr/bin/env bash
-# bluegreen.sh — reserved-public-IP blue/green pair management for the OCI A1 VMs.
+# bluegreen.sh — reserved-public-IP blue/green pair management for OCI VMs.
 #
-# The go-live topology is ONE instance (esellar-green). This tool is the
-# DORMANT future capability: when a second instance is warranted
-# (zero-downtime upgrades, risky migrations), it becomes a two-instance pair
-# sharing one RESERVED public IP — the internet-facing address never changes,
-# the flip is one OCI API call, rollback is the same call reversed.
+# A deployment can start as ONE instance; this tool is the DORMANT future
+# capability: when a second instance is warranted (zero-downtime upgrades,
+# risky migrations), it becomes a two-instance pair sharing one RESERVED
+# public IP — the internet-facing address never changes, the flip is one OCI
+# API call, rollback is the same call reversed.
 #
-# Colors are instance display names: esellar-blue / esellar-green.
+# Colors are instance display names: <app>-blue / <app>-green (defaults:
+# esellar-blue / esellar-green).
 # The reserved IP is derived from live OCI state — no local state file.
 #
 # Usage:
@@ -17,13 +18,13 @@
 #   kampodine bluegreen flip --to <color>       # ACME-first health-gated flip (see below)
 #   kampodine bluegreen rollback                # unassign to DORMANT + holder guest cleanup
 #
-# FLIP = ACME-FIRST (closes the 2026-10-07 pt2 serving-leg gap):
+# FLIP = ACME-FIRST:
 #   1. health gate on the target's own IP
 #   2. anchor.conf written on the TARGET guest over ssh — the esellar-anchor
 #      watcher service (shipped by vm-prepare) configures the anchor private
 #      address within one interval; flip waits for `ip addr` to show it
 #   3. OCI assigns the reserved IP to the target's anchor (secondary private
-#      ip — the primary holds the launch-time ephemeral, 409 live-proven)
+#      ip — the primary holds the launch-time ephemeral and rejects a second public ip)
 #   4. ACME on the TARGET's kamal-proxy for the reserved-IP sslip hostname
 #      (`podman exec kamal-proxy kamal-proxy deploy --host=<raddr-dashes>
 #      .sslip.io --tls`): HTTP-01 needs the hostname to already resolve to
@@ -38,7 +39,7 @@
 #   5. verify https through the reserved ip (curl --resolve, valid cert for
 #      the sslip name + /up 200) and the served sha — only then: FLIPPED.
 #   Any post-assign failure auto-rolls back: the reserved ip goes to the
-#   other color's EXISTING anchor (lookup-ONLY — drills never mint green-side
+#   other color's EXISTING anchor (lookup-ONLY — rollback never creates target-side
 #   artifacts) or, when none exists, back to UNASSIGNED/dormant; the failed
 #   target's anchor.conf is removed and its anchor address deleted.
 #
@@ -51,16 +52,16 @@
 #   1. NATIVE  — a UEFI_64 esellar-alpine* custom image exists in the
 #      compartment: launch it directly (the golden image boots as-is).
 #   2. INJECT (provision-via-migrate) — OCI pins imported custom images to
-#      firmware=BIOS and A1/Ampere is UEFI-only (exhaustively proven,
-#      RUNBOOK §Blue-green), but green itself runs Alpine on a boot volume
-#      whose image metadata is the Ubuntu PLATFORM image: green was built by
+#      firmware=BIOS and A1/Ampere is UEFI-only, but the template instance
+#      itself runs Alpine on a boot volume
+#      whose image metadata is the Ubuntu PLATFORM image: it was built by
 #      platform-image launch + disk injection. With no UEFI custom image,
 #      provision queries the template instance's LIVE image-id (never
 #      hardcoded — proven A1-launchable, since the template runs on it),
 #      launches from it with the ops ssh key, then streams the golden qcow2
 #      onto the new instance's boot disk (qemu-img convert -> gzip | ssh
 #      'gunzip | sudo dd', reboot, verify /etc/alpine-release). The instance
-#      record keeps the platform image metadata — exactly like green.
+#      record keeps the platform image metadata — exactly like the template.
 #
 # Env: OCI_PROFILE (default esellar-api), OCI_COMPARTMENT (default esellar).
 # Injection extras: ALPINE_QCOW2 (golden disk path), OPS_SSH_PUBKEY (ops
@@ -72,7 +73,7 @@ set -euo pipefail
 
 PROFILE="${OCI_PROFILE:-esellar-api}"
 COMPARTMENT_NAME="${OCI_COMPARTMENT:-esellar}"
-APP_HOST_HEADER="${APP_HOST_HEADER:-84-13-128-216.sslip.io}"
+APP_HOST_HEADER="${APP_HOST_HEADER:-app.example.com}"
 REPO_ROOT="${REPO_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)}"
 SSH_OPTS=(-o ConnectTimeout=6 -o BatchMode=yes -o StrictHostKeyChecking=accept-new)
 
@@ -128,8 +129,7 @@ primary_vnic_of() {
 # reserved_anchor_ip <vnic_ocid> -> private-ip ocid to anchor the reserved
 # public ip on. OCI allows ONE public ip per private ip: the PRIMARY private
 # ip holds the instance's launch-time EPHEMERAL public ip, so assigning the
-# reserved there is a 409 Conflict ("already has a public IP", live-proven
-# 2026-10-07). The reserved anchors on a SECONDARY private ip instead: both
+# reserved there is a 409 Conflict ("already has a public IP"). The reserved anchors on a SECONDARY private ip instead: both
 # colors keep their ephemeral address + reachability, the flip moves only
 # the reserved ip between secondaries.
 # existing_anchor_ip <vnic> -> the SECONDARY private-ip ocid or empty.
@@ -254,8 +254,8 @@ flip_failure_rollback() {
 
 # instance_healthy <ephemeral_ip> -> ssh + loopback app check.
 # busybox wget, NOT curl: the golden image is deliberately minimal (ssh +
-# OpenRC + busybox) and ships no curl (2026-10-07 flip attempt 3: the gate
-# failed "unhealthy" on a healthy blue because curl is absent).
+# OpenRC + busybox) and ships no curl (a curl-based gate reports
+# "unhealthy" for a healthy instance because curl is absent).
 instance_healthy() {
   local ip="$1"
   [[ -n "$ip" ]] || return 1
@@ -264,8 +264,8 @@ instance_healthy() {
 }
 
 # instance_wait_running <iid> — poll lifecycle-state to RUNNING. The OCI CLI's
-# `instance get` has NO --wait-for-state option (3.94.1: "No such option" —
-# the 2026-10-07 drill's first provision died on exactly that), so poll.
+# `instance get` has NO --wait-for-state option (CLI 3.94.1: "No such
+# option"), so poll.
 # Dies on the terminal-bad states; everything else (PROVISIONING, STARTING…)
 # keeps the loop going.
 instance_wait_running() {
@@ -298,7 +298,7 @@ inject_alpine() {
   # IP runs sshd on TWO different host keys (Ubuntu platform first boot ->
   # injected Alpine first boot). accept-new takes the first, then refuses
   # the CHANGED key after the reboot — the user's known_hosts would wedge
-  # the Alpine verify forever (2026-10-07 live drill). The scrub below
+  # the Alpine verify forever. The scrub below
   # clears the phase file between the two boots; the user's file is never
   # touched.
   kh="$(mktemp "${TMPDIR:-/tmp}/esellar-inject-kh.XXXXXX")"
@@ -323,12 +323,12 @@ inject_alpine() {
   rm -f "$raw"
   # ClientAlive keepalives on the reboot call: reboot -f kills the platform
   # sshd WITHOUT closing the TCP session, and ConnectTimeout only bounds
-  # connection ESTABLISHMENT — the pt3 drill hung the whole provisioner on
-  # that wedged session (the guest was long up when the client gave up).
+  # connection ESTABLISHMENT — a wedged session hangs the whole provisioner
+  # (the guest is long up when the client gives up).
   # ClientAliveCountMax x Interval bounds a dead session to ~15s.
   say "inject: rebooting into the injected disk (reboot -f — the old fs is gone)…"
-  # Surface the reboot failure: `|| true` here once false-INJECTED (Phase-4
-  # rehearsal finding 2026-10-07) — the wedged Ubuntu guest kept answering
+  # Surface the reboot failure: a `|| true` here once false-INJECTED — the
+  # wedged (un-rebooted) guest kept answering
   # ssh and the probe below accepted its banner as "Alpine boots". The
   # reboot must SUCCEED for the inject to be real (the disk was replaced).
   if ! iss -o ClientAliveInterval=5 -o ClientAliveCountMax=3 "${ruser}@${ip}" 'sudo reboot -f' >/dev/null 2>&1; then
@@ -341,8 +341,8 @@ inject_alpine() {
   rel=""
   for ((i = 1; i <= probe_tries; i++)); do
     rel="$(iss "root@${ip}" 'cat /etc/alpine-release' 2>/dev/null || true)"
-    # Verify the RELEASE STRING, not non-empty output: the Phase-4 rehearsal
-    # false-INJECTED when the un-rebooted Ubuntu guest's ssh banner satisfied
+    # Verify the RELEASE STRING, not non-empty output: a non-empty check
+    # false-INJECTS when the un-rebooted platform guest's ssh banner satisfies
     # a non-empty check. /etc/alpine-release only exists on a real Alpine
     # boot and reads 3.x for every image we ship.
     if [[ "$rel" =~ ^3\.[0-9]+\.[0-9]+ ]]; then break; fi
@@ -436,13 +436,13 @@ case "$cmd" in
       [[ "$image" == ocid1.image* ]] || die "template instance has no resolvable image-id — cannot launch or inject"
       mode="inject"
       qcow2="${ALPINE_QCOW2:-${REPO_ROOT}/infra/alpine-host/build/esellar-alpine-3.22.6-aarch64.qcow2}"
-      [[ -f "$qcow2" ]] || die "golden qcow2 not found: $qcow2 (build via packer, RUNBOOK § 1, or set ALPINE_QCOW2)"
+      [[ -f "$qcow2" ]] || die "golden qcow2 not found: $qcow2 (build via packer, or set ALPINE_QCOW2)"
       command -v qemu-img >/dev/null 2>&1 || die "qemu-img not found in PATH (brew install qemu) — required for the qcow2 -> raw conversion"
       # ops ssh public key for the platform-image first boot. OPS_SSH_PUBKEY
       # (explicit file) wins; else derive from the ssh AGENT (ssh-add -L) —
       # the agent key is what every kampodine ssh + the golden image's baked
       # ops key expect; ~/.ssh/id_ed25519.pub can be a stale personal key
-      # (2026-10-07 drill: launch with the stale pub = unreachable instance).
+      # (launching with a stale pub = unreachable instance).
       if [[ -n "${OPS_SSH_PUBKEY:-}" ]]; then
         [[ -f "$OPS_SSH_PUBKEY" ]] || die "ops ssh public key not found: $OPS_SSH_PUBKEY (set OPS_SSH_PUBKEY or load the key into the agent)"
         keyfile="$OPS_SSH_PUBKEY"
@@ -465,7 +465,7 @@ case "$cmd" in
     iid="$(oci compute instance launch "${launch_args[@]}" --profile "$PROFILE" --query 'data.id' --raw-output)"
     say "LAUNCHED esellar-$color: $iid"
     if [[ "$mode" == "native" ]]; then
-      say "next (RUNBOOK § start-fresh): wait RUNNING -> ssh in -> kampodine vm-prepare -> kampodine deploy --host root@<ephemeral-ip>"
+      say "next: wait RUNNING -> ssh in -> kampodine vm-prepare -> kampodine deploy --host root@<ephemeral-ip>"
       say "then 'bluegreen.sh flip --to $color' (health-gated) once its app checks green."
       exit 0
     fi
@@ -560,7 +560,7 @@ case "$cmd" in
     ;;
 
   rollback)
-    # DORMANT rollback (2026-10-07 pt3 contract): holder guest cleanup
+    # DORMANT rollback: holder guest cleanup
     # (anchor.conf removal + anchor address delete — the flip tool's explicit
     # job; the esellar-anchor watcher is add-only) then the OCI unassign
     # (documented CLI semantics: an empty --private-ip-id unassigns). For a

package/scripts/deploy.sh

@@ -20,13 +20,14 @@
 #   kampodine deploy --version <sha7>     # stream an existing local build
 #   kampodine deploy --rollback [<sha7>]  # default: previous
 #   kampodine deploy --host root@<ip> ... # target VM override
+#   kampodine deploy --dockerfile apps/api-go/Dockerfile.cutover  # Go api image
 #   --skip-smoke      # skip the public smoke (behind a not-yet-switched proxy)
 #   --refresh-config  # ansible container-service refresh BEFORE restart
 set -euo pipefail
 
 REPO_ROOT="$(git rev-parse --show-toplevel)"
-ESPELLAR_HOST="${ESPELLAR_HOST:-root@84.13.128.216}"
-PROXY_HOST="${PROXY_HOST:-84-13-128-216.sslip.io}"
+ESPELLAR_HOST="${ESPELLAR_HOST:-}"
+PROXY_HOST="${PROXY_HOST:-app.example.com}"
 ENV_FILE_REMOTE="/etc/esellar/env"
 DEPLOYED_SHA_FILE="/etc/esellar/deployed-sha"
 ENV_CLEAR_KEYS='^(NODE_ENV|PORT|LIBSQL_TENANT_DIR|LIBSQL_API_MOUNT|STATIC_SPA_MOUNT)='
@@ -36,7 +37,21 @@ MODE="deploy"
 VERSION=""
 SKIP_SMOKE=0
 REFRESH_CONFIG=0
-SSH_KEY="${ESPELLAR_SSH_KEY:-}"
+# SSH key resolution — GENERIC, no hardcoded personal paths:
+#   1. --ssh-key flag           (explicit, per-invocation)
+#   2. KAMPODINE_SSH_KEY env    (project-level: direnv / .envrc / export)
+#   3. ESSELLAR_SSH_KEY env     (legacy alias, kept for existing setups)
+#   4. empty → ssh-agent and/or the operator's ~/.ssh/config Host block
+#      (the POSIX way: per-host IdentityFile belongs in ssh config, not here)
+if [ -n "${KAMPODINE_SSH_KEY:-}" ]; then
+    SSH_KEY="$KAMPODINE_SSH_KEY"
+else
+    SSH_KEY=""
+fi
+# Default image recipe = the TS api Containerfile. The Go cutover image rides
+# --dockerfile apps/api-go/Dockerfile.cutover (build context stays the repo
+# root for BOTH — the cutover Dockerfile path-prefixes its COPYs).
+DOCKERFILE="${KAMPODINE_DOCKERFILE:-apps/api/Containerfile}"
 
 say() { printf '\033[1;34m[deploy]\033[0m %s\n' "$*"; }
 die() { printf '\033[1;31m[deploy] FAIL:\033[0m %s\n' "$*" >&2; exit 1; }
@@ -53,11 +68,13 @@ while [[ $# -gt 0 ]]; do
       ;;
     --skip-smoke) SKIP_SMOKE=1; shift ;;
     --refresh-config) REFRESH_CONFIG=1; shift ;;
+    --dockerfile) DOCKERFILE="$2"; shift 2 ;;
     -h|--help) usage ;;
     *) die "unknown argument: $1 (--help)" ;;
   esac
 done
 [[ "$VERSION" != *..* && "$VERSION" =~ ^[0-9a-f]{4,40}$|^$ ]] || die "--version must be a git sha fragment"
+[ -n "$ESPELLAR_HOST" ] || die "set ESPELLAR_HOST=root@<vm-ip> (or a ~/.ssh/config Host alias via --host)"
 
 SSH_ARGS=(-o ConnectTimeout=10 -o BatchMode=yes)
 [[ -n "$SSH_KEY" ]] && SSH_ARGS+=(-i "$SSH_KEY")
@@ -65,7 +82,7 @@ SSH_ARGS=(-o ConnectTimeout=10 -o BatchMode=yes)
 # shellcheck disable=SC2029
 vm() { ssh "${SSH_ARGS[@]}" "$ESPELLAR_HOST" "$1"; }
 
-# --- macOS ssh-agent quirk (deploy-machine runbook) ---------------------------
+# --- macOS ssh-agent quirk (first deploy from a fresh machine) ---------------
 if [[ "$(uname -s)" == "Darwin" ]]; then
   SSH_AUTH_SOCK="$(launchctl getenv SSH_AUTH_SOCK 2>/dev/null || true)"
   export SSH_AUTH_SOCK
@@ -85,10 +102,16 @@ podman info >/dev/null 2>&1 || die "podman machine not reachable (podman machine
 
 # --- build (deploy mode always builds HEAD — cached layers keep it minutes) ----
 if [[ "$MODE" == "deploy" ]]; then
-  say "building linux/arm64 (VITE_BUILD_ID=$VER — build identity, never remove: 2026-09-10 stale-tab pin)…"
+  if [[ "$DOCKERFILE" == "apps/api/Containerfile" ]]; then
+    say "building linux/arm64 (VITE_BUILD_ID=$VER — build identity, never remove)…"
+    BUILD_ARG=("VITE_BUILD_ID=$VER")
+  else
+    say "building linux/arm64 ($DOCKERFILE, GIT_SHA=$VER)…"
+    BUILD_ARG=("GIT_SHA=$VER")
+  fi
   podman build --platform linux/arm64 \
-    -f apps/api/Containerfile \
-    --build-arg VITE_BUILD_ID="$VER" \
+    -f "$DOCKERFILE" \
+    --build-arg "${BUILD_ARG[0]}" \
     -t "$IMAGE:$VER" \
     . || die "podman build failed"
   # Same-origin contract: VITE_API_URL / VITE_LIBSQL_API_URL stay UNSET —
@@ -135,10 +158,15 @@ fi
 say "rc-service esellar-api restart (supervise-daemon: stop-old/start-new podman run on the retagged :latest)…"
 vm "rc-service esellar-api restart" || die "esellar-api restart failed (rc-service esellar-api status)"
 
-say "health probe (exec-fetch /api/auth/ok + served-sha — deploy-api.sh pattern)…"
+say "health probe (host-side wget /api/auth/ok + served-sha — works for node AND scratch images)…"
 HEALTH_OK=0
 for _ in $(seq 1 30); do
-  if vm "podman exec esellar-api node -e \"fetch('http://127.0.0.1:'+(process.env.PORT||8080)+'/api/auth/ok').then(r=>r.text()).then(t=>{const m=JSON.parse(t);if(m.git!=='$VER'){console.error('served sha mismatch:',t);process.exit(1)}console.log('HEALTH OK:',t)}).catch(e=>{console.error('HEALTH FAIL:',e.message);process.exit(1)})\"" 2>/dev/null; then
+  # wget runs on the VM (busybox, -p 8080:8080 publish); the served-sha
+  # grep runs LOCALLY — remote grep quoting is fragile (busybox BRE
+  # (busybox BRE alternation + nested quotes → permanent false-negative).
+  # grep -E keeps the alternation portable across BSD/GNU/busybox.
+  if vm "wget -qO- -T 3 http://127.0.0.1:8080/api/auth/ok 2>/dev/null" \
+      | grep -qE "\"(git|build)\":\"$VER"; then
     HEALTH_OK=1
     break
   fi

package/scripts/image-import.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # image-import.sh — upload the packer-built qcow2 to Object Storage and import
-# it as an OCI custom image (runs on the BUILD Mac; the VM never touches OCI
-# APIs — see backup-tenants-par.sh for the no-agent backup path).
+# it as an OCI custom image (runs on the BUILD machine; the VM never touches
+# OCI APIs).
 #
 # VALIDATED CONSTRAINTS this script encodes:
 # - Alpine is NOT in OCI's supported custom-image import OS list -> the import
@@ -93,7 +93,7 @@ oci os object put -bn "$BUCKET" --profile "$PROFILE" --file "$IMAGE" --name "$OB
   || die "object upload failed (bucket exists? oci os bucket create -bn $BUCKET -c $COMPARTMENT_OCID)"
 
 say "importing as custom image '$IMAGE_NAME' (self-supported: PARAVIRTUALIZED)…"
-# A1/Ampere firmware gate (2026-10-07 drill, empirically exhausted):
+# A1/Ampere firmware gate (OCI platform behavior, pinned empirically):
 # OCI pins imported images to launch-options firmware=BIOS. It is NOT
 # derived from the --operating-system string (a recognized aarch64 string
 # still yields BIOS) and NOT re-derivable via `compute image update` (OS
@@ -130,15 +130,15 @@ for _ in $(seq 1 120); do
 done
 [[ "$STATE" == "AVAILABLE" ]] || die "import did not become AVAILABLE in 30m (state: $STATE)"
 
-# Firmware verdict — A1/Ampere (our target shape) rejects BIOS-pinned images
+# Firmware verdict — A1/Ampere (UEFI-only) rejects BIOS-pinned images
 # at launch (see the import-call comment above). Loud, non-fatal: other
 # (x86) shapes launch fine from a BIOS image.
 IMPORT_FIRMWARE="$(oci compute image get --image-id "$IMPORT_JSON" --profile "$PROFILE" --query 'data."launch-options"."firmware"' --raw-output 2>/dev/null || echo UNKNOWN)"
 if [[ "$IMPORT_FIRMWARE" != "UEFI_64" ]]; then
   say "WARN: import landed firmware=$IMPORT_FIRMWARE — VM.Standard.A1.Flex (Ampere, UEFI-only) WILL reject this image at launch."
-  say "      OCI has no import-time firmware control (drill-proven 2026-10-07): the sanctioned A1 route is"
+  say "      OCI has no import-time firmware control: the sanctioned A1 route is"
   say "      capture-from-instance: boot the qcow2 elsewhere, then 'oci compute image create --instance-id <running-a1>'."
-  say "      x86 shapes CAN launch this image directly. See infra/alpine-host/RUNBOOK.md § blue-green."
+  say "      x86 shapes CAN launch this image directly."
 fi
 
 if [[ $KEEP_OBJECT -eq 0 ]]; then
@@ -154,5 +154,5 @@ say "next:"
 if [[ "$IMPORT_FIRMWARE" == "UEFI_64" ]]; then
   say "  A1-ready. kampodine bluegreen provision <blue|green> picks this image (newest esellar-alpine*)."
 else
-  say "  A1 launch will REJECT this image (firmware $IMPORT_FIRMWARE) — see the WARN above / RUNBOOK § blue-green."
+  say "  A1 launch will REJECT this image (firmware $IMPORT_FIRMWARE) — see the WARN above."
 fi

package/scripts/status.sh

@@ -2,10 +2,10 @@
 # status.sh — one command: what is LIVE (through the proxy) + the blue/green
 # pair view (instances, reserved IP, health).
 #
-# Env: APP_HOST_HEADER (default: the prod host), OCI_PROFILE, OCI_COMPARTMENT.
+# Env: APP_HOST_HEADER (default: app.example.com), OCI_PROFILE, OCI_COMPARTMENT.
 set -euo pipefail
 HERE="$(cd "$(dirname "$0")" && pwd)"
-HOST="${APP_HOST_HEADER:-84-13-128-216.sslip.io}"
+HOST="${APP_HOST_HEADER:-app.example.com}"
 
 say() { printf '%s\n' "$*"; }
 

package/scripts/vm-prepare.sh

@@ -1,16 +1,14 @@
 #!/usr/bin/env bash
-# vm-prepare.sh — first-run host prep for THE production Alpine VM.
+# vm-prepare.sh — first-run bootstrap for a fresh Alpine VM.
 #
-# START-FRESH (owner decision 2026-10-04): the old Ubuntu "blue" VM is
-# ABANDONED — dead, not restored. This fresh Alpine VM is production from day
-# one: no blue->green flip, no cert carry; the first TLS certificate issues
-# during the first deploy.
+# The VM goes to production from its first boot: no blue->green flip, no
+# cert carry; the first TLS certificate issues during the first deploy.
 #
 # Alpine ships NO systemd anywhere (verified v3.22 main/community + edge; the
 # golden image boots OpenRC) — everything here is OpenRC-native:
 #   1. sanity gates (UEFI boot, OpenRC tooling; sshd hardening is
-#      ENSURED — drop-in + Include + restart — then gated: the golden image
-#      predates the baked hardening, RUNBOOK §Blue-green pt2 gap)
+#      ENSURED — drop-in + Include + restart — then gated: a fresh golden
+#      image may predate the baked hardening drop-in)
 #   2. apk repositories: ensure the v3.22 community repo (podman lives there)
 #   3. podman stack: podman podman-docker crun catatonit netavark
 #      aardvark-dns fuse-overlayfs
@@ -92,7 +90,7 @@ REGISTRIES
 
 cat > "$TMPDIR_LOCAL/60-esellar.conf" <<'SYSCTL'
 # Managed by packages/kampodine/scripts/vm-prepare.sh — do not hand-edit.
-# OpenRC contract (2026-10-04): let unprivileged/container paths bind port 80
+# OpenRC contract: let unprivileged/container paths bind port 80
 # (kamal-proxy publishes 80+443; belt-and-braces for a future rootless move).
 net.ipv4.ip_unprivileged_port_start=80
 SYSCTL
@@ -211,8 +209,7 @@ cat > "$TMPDIR_LOCAL/esellar-anchor.sh" <<'ANCHOR_WATCHER'
 # OCI assigns the reserved PUBLIC ip to a SECONDARY private ip ("the anchor")
 # on the instance VNIC, but this image has NO oracle-cloud-agent: nothing
 # configures that private ip inside the guest, so packets to the reserved ip
-# die until the address exists on the interface (RUNBOOK §Blue-green,
-# 2026-10-07 pt2 serving-leg gap). `kampodine bluegreen flip` writes
+# die until the address exists on the interface. `kampodine bluegreen flip` writes
 # /etc/esellar/anchor.conf over ssh at flip time; this watcher polls it and
 # runs `ip addr add` within one interval. The unit is enabled+started on every
 # VM by default and is INERT without the conf — a VM that never flips never
@@ -308,12 +305,12 @@ INITD_ANCHOR
 cat > "$TMPDIR_LOCAL/sshd-hardening.conf" <<'SSHD_HARDENING'
 # KEEP IN SYNC with ansible/roles/alpine-base/files/sshd-hardening.conf
 # (byte-for-byte — ansible owns the file afterwards, rendered-content
-# convention). Ensured BEFORE the hardening gate below: the golden image
-# predates the baked drop-in (RUNBOOK §Blue-green pt2 gap, closed pt3) and
+# convention). Ensured BEFORE the hardening gate below: a fresh golden image
+# may predate the baked drop-in and
 # `sshd -T` reports passwordauthentication yes on a fresh VM.
 # Keys-only management: this VM's ssh surface is the ONLY management path
-# (OCI security lists keep 22 closed to the world; access via temporary
-# scoped rule or bastion — infra/oci/README.md model still applies).
+# (cloud security lists keep 22 closed to the world; access via temporary
+# scoped rule or bastion).
 PasswordAuthentication no
 KbdInteractiveAuthentication no
 PermitRootLogin prohibit-password
@@ -468,8 +465,8 @@ done
 # --- 6. optional: pre-pull the app image over the registry tunnel ---------------
 if [[ $DO_PULL -eq 1 ]]; then
   say "pre-pulling the app image through the registry tunnel (fail BEFORE the first deploy)…"
-  # busybox wget, NOT curl: the golden image ships no curl (alpine-base
-  # installs it later; vm-prepare runs BEFORE any ansible — pt3 live)
+  # busybox wget, NOT curl: the golden image ships no curl (ansible
+  # installs it later; vm-prepare runs BEFORE any ansible)
   vm 'busybox wget -q -O /dev/null http://127.0.0.1:5000/v2/' || {
     pkill -f "ssh.*-R 5000" 2>/dev/null || true; sleep 1
     nohup ssh -R 5000:127.0.0.1:5000 -N -o ServerAliveInterval=30 -o ExitOnForwardFailure=yes "$HOST" >/tmp/esellar-tunnel.log 2>&1 &