kampodine 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,161 @@
-# Temporary Holding Version
+# kampodine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**kam**al + **pod**man + alpi**ne** — Kamal-style deploys for Alpine + Podman hosts, built on [kamal-proxy](https://github.com/basecamp/kamal-proxy).
+
+## Why this exists
+
+[kamal](https://kamal-deploy.org) is a great deploy tool with one hard
+requirement pair: **Docker engine and systemd on the target host**. If you run
+Alpine Linux — or a strict-podman fleet with no Docker anywhere — kamal cannot
+deploy for you:
+
+- **Alpine ships no systemd at all.** Not in main, community, or edge
+  (verified on v3.22). OpenRC is the init system, period.
+- **Not every fleet runs Docker.** Rootful Podman under OpenRC
+  `supervise-daemon` is a perfectly good way to host containers — kamal just
+  can't talk to it.
+- **kamal-proxy was never the problem.** It's a container image — completely
+  init-agnostic. Host routing, ACME TLS, and gapless target swaps via
+  `kamal-proxy deploy` work fine on an Alpine + Podman host.
+
+kampodine keeps kamal-proxy as the TLS edge and replaces everything around it
+with Alpine-native pieces:
+
+| kamal assumes | kampodine uses |
+|---|---|
+| Docker engine | Podman (rootful, no Docker anywhere) |
+| systemd units | OpenRC `supervise-daemon` services |
+| Container registry | `podman save \| ssh podman load` — a plain SSH stream |
+| kamal proxy orchestration | kamal-proxy itself, unchanged |
+
+## What it does
+
+Same mental model as kamal: **build → ship → health-gate → cutover → instant
+rollback.**
+
+```
+kampodine deploy:
+  podman build --build-arg BUILD_ID=<git sha>        # committed tree only
+  podman save <img>:<sha>  |  ssh <host> podman load
+  podman tag <img>:<sha> <img>:latest                # on the VM
+  env file generation -> /etc/<app>/env (0600)       # from your secret store
+  rc-service <app> restart
+  health endpoint must report the DEPLOYED sha       # health gate
+  kamal-proxy deploy <host> -> <target>              # gapless cutover
+  public smoke: health + build-id endpoints
+```
+
+- **`kampodine deploy`** — stream deploy; `--version <sha>` restreams an
+  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
+
+## Kamal parity
+
+| kamal | kampodine |
+|---|---|
+| `kamal deploy` | `kampodine deploy` |
+| `kamal rollback` | `kampodine deploy --rollback [sha]` |
+| `kamal details` | `kampodine bluegreen status` |
+| `kamal proxy …` | kamal-proxy container, unchanged |
+| `kamal app exec/logs` | `ssh root@<host>` |
+| `kamal reboot / app boot` | `rc-service <app> restart` over SSH |
+
+## Building the expected image
+
+kampodine's target host is a **converged Alpine image** — Alpine (aarch64 or
+x86_64) with the podman runtime, OpenRC services, and kernel settings the
+deploy flow relies on. The reference build pipeline:
+
+1. **packer + qemu (UEFI)** boots the Alpine `virt` ISO. Boot is driven over
+   the **serial console**, not VNC — the ISO's VGA tty has no getty; a serial
+   bootstrap helper handles the login prompt and ash's `ESC[6n` cursor query,
+   then types one line that brings up DHCP and fetches the bootstrap script.
+2. **install** runs `setup-disk` under UEFI (ESP + grub-efi, `--removable`
+   fallback for hosts with fresh NVRAM), sanitizes apk repos, installs
+   `python3` (ansible runtime) + `openssh`, enables boot-critical OpenRC
+   services, bakes your public key, reboots.
+3. **ansible converge** installs the podman stack — podman, netavark,
+   aardvark-dns, **iptables** (netavark needs it), the **cgroups** service
+   (cloud VMs boot without one), `ip_unprivileged_port_start=80` sysctl — and
+   lays down `supervise-daemon` templates for app + kamal-proxy. **The same
+   playbook converges the golden image and repairs live drift**: one
+   convergence path, the image is by construction what the playbook produces.
+4. **ship the qcow2** to your cloud. On OCI: import **from a launched
+   instance** (or boot-volume seeding) — raw QCOW2 object imports land
+   x86-flagged and won't boot on Ampere. `kampodine image-import` +
+   `kampodine vm-prepare` handle that path.
+5. First deploy issues TLS (ACME) via kamal-proxy — no cert carry.
+
+Verify a build by booting the qcow2 locally (qemu UEFI boot, serial console)
+before importing — the image should reach a working sshd with the podman
+stack installed.
+
+## Shipping the image: mirror vs no-mirror
+
+Two ways to get the built container image onto the target — kampodine
+automates the second; the first is a documented recipe:
+
+**No-mirror (default): the SSH stream.** `podman save | ssh podman load` over
+the deploy's own SSH connection. Nothing exists between you and the VM: no
+registry, no tunnel, no extra ports, no credentials beyond SSH.
+
+- ✅ zero infrastructure; works air-gapped; nothing to keep alive
+- ✅ sha-tagged images land atomically; `podman load` dedupes layers by digest
+- ⚠️ each deploy streams the full image tar; no cross-deploy layer cache
+
+**Mirror (optional): any OCI registry.** `podman push` the sha-tagged image to
+a registry the VM can reach; the VM `podman pull`s and retags `:latest` — the
+health-gate/cutover tail is identical. Works with hosted registries (GHCR,
+Docker Hub, cloud registries) or a local one mirrored over an SSH reverse
+tunnel (`ssh -R 5000:127.0.0.1:5000`).
+
+- ✅ layer caching (fast repeated deploys), multi-target fan-out, CI-native
+- ⚠️ requires registry reachability + credentials on the VM
+- ⚠️ macOS note: AirPlay listens on :5000 by default — pick another port for
+  a local registry
+
+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.
+
+## Prerequisites
+
+Deploy machine: node ≥ 20, podman, ssh key access to the target, `oci` CLI
+(for bluegreen / image-import), and whatever secret-resolution your env-file
+step uses (kampodine is agnostic; the reference setup uses
+[varlock](https://varlock.dev) + pass).
+
+Target: a converged Alpine + Podman + OpenRC host (see above), reachable over
+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).
+
+## License
+
+Copyright (c) 2026 talha7k — **AGPL-3.0** (see [LICENSE](./LICENSE)).
+
+Copyleft with teeth: anyone who uses, modifies, or hosts kampodine —
+including as a network service — must publish their source under AGPL-3.0,
+and original attribution must be preserved.

package/cli.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const pkgDir = dirname(fileURLToPath(import.meta.url));
+const { version } = JSON.parse(readFileSync(join(pkgDir, "package.json"), "utf8"));
+
+const commands = {
+  deploy: "deploy.sh",
+  status: "status.sh",
+  bluegreen: "bluegreen.sh",
+  "vm-prepare": "vm-prepare.sh",
+  "image-import": "image-import.sh",
+  migrate: "migrate.sh",
+};
+
+const usage = `kampodine — kamal-alternative CLI for Alpine + Podman deploys, built on kamal-proxy
+
+Usage: kampodine <command> [args...]
+
+Commands:
+  deploy         stream deploy (podman save | ssh podman load) with sha-verified health gate; --rollback [sha] = instant image-tag rollback
+  bluegreen      reserved-IP blue/green pair: status (pair + reserved IP + health) | init | provision | flip | rollback
+  vm-prepare     first-run bootstrap of a bare Alpine host (OpenRC + podman stack)
+  image-import   golden qcow2 -> OCI custom image
+  migrate        tenant db migrations over SSH
+
+All further args pass through to the underlying script.
+`;
+
+const [cmd, ...args] = process.argv.slice(2);
+
+if (!cmd || cmd === "--help" || cmd === "-h") {
+  process.stdout.write(usage);
+  process.exit(0);
+}
+if (cmd === "--version") {
+  process.stdout.write(`${version}\n`);
+  process.exit(0);
+}
+
+const script = commands[cmd];
+if (!script) {
+  process.stderr.write(`kampodine: unknown command: ${cmd}\n\n${usage}`);
+  process.exit(2);
+}
+
+const result = spawnSync("bash", [join(pkgDir, "scripts", script), ...args], {
+  stdio: "inherit",
+  env: process.env,
+});
+if (result.error) {
+  process.stderr.write(`kampodine: ${result.error.message}\n`);
+  process.exit(1);
+}
+process.exit(result.status ?? 1);

package/kampodine.md

@@ -0,0 +1,99 @@
+# kampodine — founding doc
+
+Positioning, architecture, and build-out checklist. Public README covers the
+pitch; this doc is the deeper reference.
+
+## Why this exists
+
+- **kamal (the tool) requires Docker engine + systemd on the target host.**
+- **Alpine ships no systemd at all** (verified: absent from v3.22
+  main/community + edge — OpenRC is the init, full stop).
+- **Podman-only fleets exist** — no Docker engine on any machine.
+- **kamal-proxy doesn't care about any of that** — it's a container image,
+  init-agnostic. It was never the problem; kamal's host assumptions were.
+
+So: keep kamal-proxy as the TLS edge, replace the deploy machinery around it
+with Alpine-native pieces — OpenRC `supervise-daemon`, rootful podman, and a
+plain SSH stream instead of a registry.
+
+## Positioning
+
+- A **kamal alternative** for podman + Alpine targets.
+- **Built ON kamal-proxy** — host routing, ACME TLS, gapless target swaps via
+  `kamal-proxy deploy` are all still kamal-proxy's job.
+- Same mental model as kamal: **build → ship → health-gate → cutover →
+  instant rollback**. No registry in the middle.
+
+## Commands (kamal parity)
+
+| kamal | kampodine |
+|---|---|
+| `kamal deploy` | `kampodine deploy` — stream deploy (`podman save \| ssh podman load`) |
+| `kamal rollback` | `kampodine deploy --rollback [sha]` — instant image-tag rollback |
+| `kamal details` | `kampodine bluegreen status` — pair + reserved IP + health |
+| `kamal proxy …` | unchanged — kamal-proxy container (OpenRC-supervised) |
+| `kamal app exec/logs` | `ssh root@<host>` |
+| — | `kampodine bluegreen init/provision/flip` — reserved-IP blue-green pair |
+| — | `kampodine image-import` — golden qcow2 → OCI custom image |
+| — | `kampodine vm-prepare` — first-run bootstrap of a bare Alpine host |
+| — | `kampodine migrate` — sqlite migrations over SSH |
+
+## Deploy pipeline (what `kampodine deploy` does)
+
+```
+build (BUILD_ID=<git sha>, committed tree only)
+  -> podman save <img>:<sha>  |  ssh vm podman load
+  -> podman tag <img>:<sha> <img>:latest
+  -> env file generation -> /etc/<app>/env (0600, secret-store resolved)
+  -> rc-service <app> restart
+  -> health endpoint must report the DEPLOYED sha     # health gate
+  -> kamal-proxy deploy <host> -> <target>            # gapless cutover
+  -> public smoke: health + build-id endpoints
+```
+
+Guarantees: committed-tree-only deploys (sha = build identity, verified at
+health time); the previous image stays on the VM (rollback = retag + restart);
+no registry, no tunnel, no docker, no systemd — SSH + podman only.
+
+## Checklist
+
+**Done (battle-tested in production):**
+- [x] registry-free stream deploy with sha-verified health gate + public smoke
+- [x] instant rollback (`--rollback [sha]`)
+- [x] secret-store-resolved env file generation (zero plaintext)
+- [x] kamal-proxy TLS registration + ACME (per-host)
+- [x] OpenRC golden image — packer build + single-convergence ansible roles
+- [x] `vm-prepare` start-fresh bootstrap
+- [x] blue-green reserved-IP tooling — `status`/`init`/`provision`/`flip`/
+      `rollback`; discovery, dormant reserved-IP detection, health checks,
+      and flip-guards verified against live OCI; flip E2E runs when a second
+      instance exists
+- [x] sqlite migration runner (`migrate`)
+- [x] OCI image import path (`image-import`)
+
+**In flight:**
+- [ ] npm package scaffold — bin `kampodine`, scripts shipped in-package
+- [ ] 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
+
+## Non-goals
+
+- multi-host orchestration, roles, accessory containers — kamal's scale
+  problems small fleets don't have
+- replacing kamal-proxy (that part is already right)
+
+## Prerequisites (deploy machine)
+
+node ≥ 20, podman, oci CLI (bluegreen/image-import), ssh key to the target,
+your secret-resolution tool of choice for the env step.

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "kampodine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Kamal-style deploys for Alpine + Podman hosts, built on kamal-proxy",
+  "license": "AGPL-3.0",
+  "type": "module",
+  "bin": {
+    "kampodine": "./cli.js"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:exact": "vitest run"
+  },
+  "files": [
+    "cli.js",
+    "scripts/",
+    "kampodine.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "vite": "^8.0.16",
+    "vitest": "^4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/talha7k/kampodine.git"
+  },
+  "homepage": "https://github.com/talha7k/kampodine#readme",
+  "bugs": {
+    "url": "https://github.com/talha7k/kampodine/issues"
+  }
+}