@podosoft/podokit 0.16.4 → 0.17.1

package/dist/templates/fullstack-nest-svelte/apps/web/src/lib/server/ws-upgrade.test.js

@@ -0,0 +1,134 @@
+import { PassThrough } from "node:stream";
+import { describe, expect, it } from "vitest";
+import { createUpgradeProxy, decideUpgrade, upstreamHeaders } from "./ws-upgrade.js";
+
+const allowed = new Set(["/events/ws"]);
+const handshake = { upgrade: "websocket", connection: "Upgrade", host: "app.example.com" };
+
+describe("decideUpgrade", () => {
+  it("forwards an allowed path", () => {
+    expect(decideUpgrade("/events/ws", handshake, allowed)).toEqual({
+      kind: "proxy",
+      path: "/events/ws",
+    });
+  });
+
+  it("keeps the query string", () => {
+    expect(decideUpgrade("/events/ws?room=1", handshake, allowed)).toEqual({
+      kind: "proxy",
+      path: "/events/ws?room=1",
+    });
+  });
+
+  it.each([
+    ["/events/wsx", "a path that only starts the same"],
+    ["/events/ws/", "a trailing slash"],
+    ["/admin/secrets", "an unrelated path"],
+    ["/events/../admin/secrets", "traversal that resolves elsewhere"],
+    ["//evil.example.com/events/ws", "a protocol-relative target"],
+    ["http://evil.example.com/events/ws", "an absolute target"],
+  ])("rejects %s (%s)", (url) => {
+    expect(decideUpgrade(url, handshake, allowed).kind).toBe("reject");
+  });
+
+  it("rejects a request that is not a websocket upgrade", () => {
+    expect(decideUpgrade("/events/ws", { ...handshake, upgrade: "h2c" }, allowed).kind).toBe(
+      "reject",
+    );
+  });
+
+  it("forwards nothing when no path is configured", () => {
+    expect(decideUpgrade("/events/ws", handshake, new Set()).kind).toBe("reject");
+  });
+});
+
+describe("upstreamHeaders", () => {
+  it("passes the handshake and cookie through", () => {
+    const headers = upstreamHeaders(
+      { ...handshake, cookie: "session=abc", "sec-websocket-key": "k" },
+      {},
+    );
+    expect(headers.cookie).toBe("session=abc");
+    expect(headers["sec-websocket-key"]).toBe("k");
+    expect(headers.upgrade).toBe("websocket");
+  });
+
+  it("appends to an existing forwarded chain rather than replacing it", () => {
+    const headers = upstreamHeaders(
+      { ...handshake, "x-forwarded-for": "203.0.113.7" },
+      { remoteAddress: "::ffff:10.0.0.2" },
+    );
+    expect(headers["x-forwarded-for"]).toBe("203.0.113.7, 10.0.0.2");
+  });
+
+  it("reports the scheme the client actually used", () => {
+    expect(upstreamHeaders(handshake, { encrypted: true })["x-forwarded-proto"]).toBe("https");
+    expect(upstreamHeaders(handshake, {})["x-forwarded-proto"]).toBe("http");
+  });
+});
+
+describe("createUpgradeProxy", () => {
+  function socket() {
+    const stream = new PassThrough();
+    stream.destroy = () => {
+      stream.destroyed = true;
+      return stream;
+    };
+    return stream;
+  }
+
+  it("destroys a rejected upgrade without contacting the API", () => {
+    let called = false;
+    const proxy = createUpgradeProxy({ allowed, connect: () => ((called = true), { abort() {} }) });
+    const client = socket();
+    proxy({ url: "/admin/secrets", headers: handshake }, client, null);
+    expect(called).toBe(false);
+    expect(client.destroyed).toBe(true);
+  });
+
+  it("relays the API's refusal instead of dropping the socket", () => {
+    const proxy = createUpgradeProxy({
+      allowed,
+      connect: (_options, hooks) => {
+        hooks.onResponse(401, "Unauthorized", { "content-length": "0" });
+        return { abort() {} };
+      },
+    });
+    const client = socket();
+    /** @type {string[]} */
+    const written = [];
+    client.on("data", (chunk) => written.push(chunk.toString()));
+    proxy({ url: "/events/ws", headers: handshake }, client, null);
+    expect(written.join("")).toContain("HTTP/1.1 401 Unauthorized");
+  });
+
+  it("answers 502 when the API cannot be reached", () => {
+    const proxy = createUpgradeProxy({
+      allowed,
+      connect: (_options, hooks) => (hooks.onError("ECONNREFUSED"), { abort() {} }),
+    });
+    const client = socket();
+    /** @type {string[]} */
+    const written = [];
+    client.on("data", (chunk) => written.push(chunk.toString()));
+    proxy({ url: "/events/ws", headers: handshake }, client, null);
+    expect(written.join("")).toContain("HTTP/1.1 502 Bad Gateway");
+  });
+
+  it("writes the 101 and pipes both directions once upstream upgrades", () => {
+    const upstream = socket();
+    const proxy = createUpgradeProxy({
+      allowed,
+      connect: (_options, hooks) => {
+        hooks.onUpgrade(101, { upgrade: "websocket" }, upstream, null);
+        return { abort() {} };
+      },
+    });
+    const client = socket();
+    /** @type {string[]} */
+    const written = [];
+    client.on("data", (chunk) => written.push(chunk.toString()));
+    proxy({ url: "/events/ws", headers: handshake }, client, null);
+    expect(written.join("")).toContain("HTTP/1.1 101 Switching Protocols");
+  });
+});

package/dist/templates/fullstack-nest-svelte/apps/web/vite.config.ts

@@ -7,13 +7,23 @@ import { defineConfig } from "vite";
 // browser origin so the same configuration works for both entry points.
 const inDocker = process.env.VITE_DOCKER === "1";
 
+// Dev parity for WebSocket upgrades. In production `server.js` proxies these paths to
+// the API; without the same allowlist here, a feature would work in one and not the
+// other -- which is exactly how a WebSocket gateway used to reach production dead.
+// Set WS_PROXY_PATHS in the shell that runs vite; a .env file cannot reach this file.
+const wsProxyPaths = (process.env.WS_PROXY_PATHS ?? "")
+  .split(",")
+  .map((entry) => entry.trim())
+  .filter((entry) => entry.startsWith("/"));
+const backendTarget = process.env.BACKEND_INTERNAL_URL ?? "http://localhost:5002";
+const wsProxy = Object.fromEntries(
+  wsProxyPaths.map((path) => [path, { target: backendTarget, ws: true, changeOrigin: false }]),
+);
+
 export default defineConfig({
   plugins: [tailwindcss(), sveltekit()],
-  server: inDocker
-    ? {
-        host: true,
-        port: 5001,
-        allowedHosts: true,
-      }
-    : undefined,
+  server: {
+    ...(inDocker ? { host: true, port: 5001, allowedHosts: true } : {}),
+    ...(wsProxyPaths.length ? { proxy: wsProxy } : {}),
+  },
 });

package/dist/templates/fullstack-nest-svelte/dot-agents/skills/podokit-deploy/SKILL.md

@@ -1,20 +1,65 @@
 ---
 name: podokit-deploy
-description: Plan, inspect, apply, verify, and roll back PodoKit Kubernetes releases with an explicit deployment profile and confirmation hash. Use when an agent needs to initialize a .podokit/deploy profile, diagnose a target cluster, preview a release, perform an approved deployment, inspect rollout state, verify public endpoints, or prepare an application rollback.
+description: Plan, inspect, apply, verify, and roll back PodoKit releases with an explicit deployment profile and confirmation hash, on Kubernetes or Docker Compose. Use when an agent needs to initialize a .podokit/deploy profile, diagnose a target, preview a release, perform an approved deployment, inspect rollout state, verify public endpoints, or prepare a rollback.
 ---
 
 # Deploy a PodoKit application
 
+A profile records which driver it uses, so every command below is the same for both.
+Read the profile's `driver` first and say which one you are operating.
+
+| Driver | Target | Use it when |
+| --- | --- | --- |
+| `kubernetes-helm` | a cluster context and namespace | you already run a cluster, or you need more than one node, cluster-managed rollouts, or per-workload scaling |
+| `docker-compose` | one Docker host, local or over `ssh://` | one machine is the whole deployment and a reverse proxy in front of it terminates TLS |
+
 1. Run `npx @podosoft/podokit status`, `npx @podosoft/podokit diff`, and `npx @podosoft/podokit doctor`. Stop if managed-file conflicts or unsupported framework versions could make the image unreliable.
 2. Read [references/profile.md](references/profile.md) before creating or changing a deployment profile.
-3. Run `npx @podosoft/podokit deploy doctor --profile <name>`. Resolve every failure without printing Secret values.
-4. Run `npx @podosoft/podokit deploy plan --profile <name> --release <stable-semver> --json`.
-5. Show the user the context, cluster fingerprint result, namespace, Helm release, exact images, current revision and status, actions, migration warning, and plan hash.
-6. Do not apply until the user explicitly approves that exact plan.
-7. Apply with `npx @podosoft/podokit deploy apply --profile <name> --release <stable-semver> --confirm <plan-hash>`.
-8. Run `npx @podosoft/podokit deploy status --profile <name> --json` and `npx @podosoft/podokit deploy verify --profile <name> --json`.
-9. Report the exact images, Helm revision, ready replicas, restart totals, and verification result.
+3. Make sure the images exist for that tag. Read [references/release.md](references/release.md): tagging `vX.Y.Z` runs the release workflow, which builds and pushes both images and stops there. Never apply a release whose images were not published.
+4. Run `npx @podosoft/podokit deploy doctor --profile <name>`. Resolve every failure without printing secret values.
+5. Run `npx @podosoft/podokit deploy plan --profile <name> --release <stable-semver> --json`.
+6. Show the user the driver, the target (context plus namespace and Helm release, or Docker context plus Compose project), the fingerprint result, the exact image digests, the current revision, the actions, the migration warning, and the plan hash.
+7. Do not apply until the user explicitly approves that exact plan.
+8. Apply with `npx @podosoft/podokit deploy apply --profile <name> --release <stable-semver> --confirm <plan-hash>`.
+9. Run `npx @podosoft/podokit deploy status --profile <name> --json` and `npx @podosoft/podokit deploy verify --profile <name> --json`.
+10. Report the exact images, the revision, running replicas, restart totals, and the verification result. Report `syncDrift` too: a non-empty value means containers are running locally synced artifacts and the release tag does not describe what is serving.
+
+## Iterating against a deployment is a different command
+
+If the user is changing code and wants to see it on the deployment, a release is the
+wrong loop — it rebuilds and republishes to move a few megabytes of compiled output.
+Use the `podokit-deploy-fast` skill (`podo deploy sync`, docker-compose driver only).
+Reach for a release when the change needs a migration, changes runtime dependencies,
+or is going to real users.
+
+## The migration runs against the release that is still serving
+
+Both drivers run the migration **before** the new containers start, and both keep the
+previous release serving while the new one rolls out. So a migration must be
+compatible with the code already running:
+
+- Additive changes are safe: new tables, new nullable columns, new indexes.
+- Dropping or renaming a column, or tightening a constraint, breaks the running
+  release the moment the migration commits — before any new code is live.
+- Destructive changes belong in a **second** release, after the code that stopped
+  using the column has fully rolled out.
+
+Rollback does not reverse migrations on either driver. If an older image cannot read
+the current schema, roll forward instead.
+
+## Rollback
+
+Read [references/rollback.md](references/rollback.md), preview the target revision
+without `--confirm`, show the new plan hash, and obtain explicit approval.
+
+The compose driver can only reproduce a revision whose rendered project still matches
+the current profile byte for byte; if the profile changed since, it refuses and tells
+you to roll forward.
 
-For rollback, read [references/rollback.md](references/rollback.md), preview the target revision without `--confirm`, show the new plan hash, and obtain explicit approval.
+## Boundary
 
-Never create or rotate cluster credentials, registry credentials, DNS, virtual machines, Kubernetes Secrets, or backup repositories. Never put a password, token, private key, connection URL containing credentials, or Secret value in a profile, command argument, log, or report.
+Never create or rotate cluster credentials, registry credentials, DNS records,
+virtual machines, Kubernetes Secrets, env files on a deployment host, TLS
+certificates, or backup repositories. Never put a password, token, private key,
+connection URL containing credentials, or secret value in a profile, a command
+argument, a log, or a report.

package/dist/templates/fullstack-nest-svelte/dot-agents/skills/podokit-deploy/references/profile.md

@@ -1,6 +1,10 @@
 # Deployment profile
 
-The profile at `.podokit/deploy/<name>.json` is application-owned and contains no Secret values.
+The profile at `.podokit/deploy/<name>.json` is application-owned and contains no
+secret values. It declares a `driver`, and that decides the shape of the rest of the
+document.
+
+## kubernetes-helm (default)
 
 Initialize it with an explicit kubeconfig context:
 
@@ -35,3 +39,48 @@ Required keys:
 Use `inCluster` when the generated Helm release should manage a dependency, `external` when application configuration points to an existing service, and `disabled` only when the application does not require it.
 
 Use the same stable SemVer tag for API and web. `latest`, branch tags, and empty tags are rejected. Planning resolves every deployed tag to an immutable registry digest through Docker Buildx.
+
+## docker-compose
+
+Initialize it with an explicit Docker context. The context may be local or `ssh://`,
+and it is pinned by a fingerprint of the endpoint plus the daemon ID, so repointing
+it at a different host invalidates the profile instead of deploying somewhere else.
+
+```bash
+npx @podosoft/podokit deploy init \
+  --profile production \
+  --driver docker-compose \
+  --context production \
+  --host app.example.com \
+  --secrets-dir /etc/podokit/example-app
+```
+
+The fields that differ from the Kubernetes driver:
+
+- `target`: Docker context, endpoint fingerprint, Compose project name
+- `exposure`: `bindAddress` and `port` published from the web service. It defaults to
+  `127.0.0.1`, because the expected front door is a reverse proxy on the same host —
+  binding every interface publishes the app before TLS exists
+- `workloads`: replicas plus Compose `cpus` and `memory` limits
+- `dependencies`: `managed`, `external`, or `disabled`, each with a named Docker
+  volume and the path of its env file on the target host
+- `secrets`: env-file paths and required key names, plus `registryLogin`
+
+Credentials live in env files **on the target host**, never in the profile and never
+in the rendered Compose project. The doctor reads only the key names, in a throwaway
+container that mounts the file read-only. Create those files with the host's own
+secret tooling before deploying; PodoKit does not write them.
+
+Required keys:
+
+| Env file | Required keys |
+| --- | --- |
+| API | Profile-declared keys plus enabled dependency connection keys: `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, `REDIS_PASSWORD`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` |
+| web | Only explicitly declared web keys; omitted by default |
+| PostgreSQL dependency | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` |
+| Redis dependency | `REDIS_PASSWORD` |
+| Object storage dependency | `MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` |
+
+Data volumes are declared `external`, so `docker compose down -v` cannot delete the
+database. Editing an env file changes the containers' rollout label, so the next
+apply actually restarts them instead of leaving stale environment values running.

package/dist/templates/fullstack-nest-svelte/dot-agents/skills/podokit-deploy/references/release.md

@@ -0,0 +1,64 @@
+# Publishing the images a release deploys
+
+`podo deploy` consumes images. Building them is `.github/workflows/release.yml`,
+which triggers on a `v*.*.*` tag, verifies the commit, builds both images from the
+repository root, and pushes them under that one tag. It does not roll out.
+
+```bash
+git tag v1.2.3
+git push origin v1.2.3
+```
+
+Then plan and apply as the main skill describes. `podo deploy plan` resolves the tag
+to an immutable digest, so a tag whose images were never pushed fails there rather
+than half way through a rollout.
+
+## Before the first tag: check the runner
+
+**GitHub-hosted runners are free for public repositories only.** In a private
+repository every minute is metered against the account's included Actions minutes and
+billed beyond them, and image builds are usually the most expensive job a project
+runs. A self-hosted runner consumes no Actions minutes at all.
+
+The workflow reads the choice from a variable, so it is a setting rather than an edit:
+
+| Variable | Unset | Notes |
+| --- | --- | --- |
+| `PODOKIT_RUNNER` | `["ubuntu-latest"]` | JSON array of labels. Self-hosted example: `["self-hosted","Linux","X64"]` |
+| `PODOKIT_DEPLOY_PROFILE` | `production` | which `.podokit/deploy/<name>.json` names the image repositories |
+| `PODOKIT_IMAGE_PLATFORM` | `linux/amd64` | the architecture the **deployment target** runs, not the runner's |
+
+Nothing warns when a private repository is still on the default: the workflow
+succeeds either way and the difference appears on a bill. **When asked to set up
+releases, check the repository's visibility first and say which case it is.**
+
+`PODOKIT_IMAGE_PLATFORM` is the other one worth stating out loud. Building for the
+wrong architecture produces `exec format error` at rollout — after the migration has
+already run — and building for the right one on a runner of a different architecture
+works but runs under emulation, which is slow enough to be mistaken for a problem
+with Docker.
+
+## Secrets
+
+`REGISTRY_USERNAME` and `REGISTRY_PASSWORD`, for the registry named by the profile's
+`release.apiRepository`. A robot or deploy account is enough for pushing, but some
+registries do not let a robot **create** a repository — push the first tag of a new
+repository with an account that can, or create the repository in the registry first.
+
+Never print either value, and never put one in a profile, a command argument, or a
+report.
+
+## Building by hand
+
+Only when a tag is not the right trigger. Build for the target's architecture, tag
+both images identically, and push before planning:
+
+```bash
+docker build --platform linux/amd64 -f apps/api/Dockerfile -t <api-repository>:v1.2.3 .
+docker build --platform linux/amd64 -f apps/web/Dockerfile -t <web-repository>:v1.2.3 .
+docker push <api-repository>:v1.2.3
+docker push <web-repository>:v1.2.3
+```
+
+A bare local tag cannot be deployed: it does not match the profile's stable SemVer
+pattern and cannot be resolved to a digest.

package/dist/templates/fullstack-nest-svelte/dot-agents/skills/podokit-deploy-fast/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: podokit-deploy-fast
+description: Push locally built artifacts into a running Docker Compose deployment and restart it, without building or publishing an image. Use when iterating on code against a deployed environment and a full release round trip is too slow. Not for releases, migrations, dependency changes, or anything going to real users.
+---
+
+# Sync code into a running deployment
+
+`podo deploy sync` copies this project's build output into the containers that are
+already running and restarts them. `docker-compose` driver only — read the profile's
+`driver` first and stop if it is `kubernetes-helm`, where the equivalent would have
+to reach every node and would stop being a shortcut.
+
+```bash
+npx @podosoft/podokit deploy sync --profile <name> --build
+```
+
+## Say what this does before doing it
+
+It is not a release, and the user has to understand three consequences before you run
+it:
+
+1. **The deployment will run code its image tag does not describe.** A marker file
+   records the sync and `podo deploy status` reports it under `syncDrift`.
+2. **Every connection the restarted containers hold is dropped** — WebSocket sessions,
+   in-flight requests, anything attached.
+3. **It disappears on the next release.** Container writable layers do not survive
+   recreation, so `podo deploy apply` restores the image with no cleanup step. That is
+   the property that makes this safe; do not build anything that depends on the copy
+   persisting.
+
+## When NOT to use it
+
+Use a release instead — build the images and `podo deploy apply` — when any of these
+is true. The first three are refusals the command makes itself; the last two it
+cannot detect, which is why they are your job.
+
+| Situation | Why |
+| --- | --- |
+| runtime dependencies changed | the container's `node_modules` was installed `--omit=dev` from the old manifest, so the new code imports something that is not there |
+| a release holds the deployment lock | an apply is in progress |
+| nothing is running for that project | there is no container to copy into |
+| **the change needs a migration** | sync never migrates, and a migration belongs with the release whose code needs it |
+| **the change is going to real users** | nothing is pushed, so nothing is reproducible from it |
+
+## Procedure
+
+1. Read the profile's `driver`. Stop unless it is `docker-compose`.
+2. Tell the user what will restart and that connections drop. Get agreement if anyone
+   is using the deployment.
+3. Run with `--build` unless the project is already built. `--build` compiles in the
+   order the images do — every `packages/*` before the apps — because a root build
+   script runs workspaces in manifest order and an app listed first would compile
+   against a workspace package's previous output.
+4. Report what was copied, which containers restarted, and that the deployment is now
+   in sync drift.
+5. Verify against the running deployment, not against the build: request a path the
+   change affects. If part of the build output is excluded (below), check one of
+   those paths too — that is the failure this exclusion exists to prevent, and it
+   does not make the page look broken.
+
+## Restoring the image
+
+```bash
+npx @podosoft/podokit deploy sync --profile <name> --revert
+```
+
+This recreates the containers from the Compose project **already on the target**,
+which is the description of what was actually applied — not a fresh render, which
+would reproduce the profile as it is now.
+
+A release does the same thing as a side effect, so `--revert` is for abandoning a
+sync, not a required cleanup step.
+
+## Excluding part of the build output
+
+Some of a build output can come from a toolchain the developer's machine does not
+have. Overwriting that part replaces real artifacts with an index of artifacts that
+are no longer there, and the application keeps serving pages while the missing files
+404 — so nothing looks broken. Those paths belong in the profile:
+
+```json
+{ "sync": { "exclude": ["apps/web/build/static-assets/generated"] } }
+```
+
+If you find yourself about to sync over something this machine cannot rebuild, add it
+here rather than remembering not to. `--clean` refuses while an exclude sits beneath
+a synced path, for the same reason.
+
+## Boundary
+
+Never use this to ship. Never run migrations alongside it. Never create or rotate
+credentials, and never print a secret value.

package/dist/templates/fullstack-nest-svelte/dot-claude/skills/podokit-deploy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: podokit-deploy
-description: Plan, inspect, apply, verify, and roll back PodoKit Kubernetes releases with an explicit profile and confirmation hash. Use for Kubernetes deployment and rollback work in a generated PodoKit project.
+description: Plan, inspect, apply, verify, and roll back PodoKit releases with an explicit profile and confirmation hash, on Kubernetes or Docker Compose. Use for release, rollout, and rollback work in a generated PodoKit project.
 ---
 
 # PodoKit deployment

package/dist/templates/fullstack-nest-svelte/dot-claude/skills/podokit-deploy-fast/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: podokit-deploy-fast
+description: Push locally built artifacts into a running Docker Compose deployment and restart it, without building or publishing an image. Use when iterating on code against a deployed environment and a full release round trip is too slow. Not for releases, migrations, dependency changes, or anything going to real users.
+---
+
+# PodoKit fast deployment sync
+
+Read and follow the canonical skill at `../../../.agents/skills/podokit-deploy-fast/SKILL.md`.

package/dist/templates/fullstack-nest-svelte/dot-dockerignore

@@ -6,3 +6,10 @@ dist
 **/.svelte-kit
 .git
 *.log
+
+# Real environment files never enter a build context. The build stages copy the
+# whole repository, so an .env left here is baked into an image layer even when the
+# runtime stage does not copy it -- and getting-started tells you to create one.
+.env
+.env.*
+!.env.example

package/dist/templates/fullstack-nest-svelte/dot-env.example

@@ -12,6 +12,13 @@ POSTGRES_DB=podokit
 
 # Web -> API boundary (server-side only; not exposed to the browser)
 BACKEND_INTERNAL_URL=http://localhost:5002
+
+# Exact paths the web server may proxy as WebSocket upgrades to the API, comma
+# separated. Empty means none: a SvelteKit route cannot answer an upgrade, so a
+# WebSocket gateway on the API is unreachable until it is named here. Each path is
+# matched whole and must be authorised by the API at handshake time -- a relay that
+# forwards anything is an open tunnel to every private route.
+WS_PROXY_PATHS=
 CORS_ORIGIN=http://localhost:5001
 # adapter-node request limit; leave room for a 2 MiB multipart upload
 BODY_SIZE_LIMIT=3M

package/dist/templates/fullstack-nest-svelte/dot-github/workflows/release.yml

@@ -0,0 +1,142 @@
+# Build and publish the release images for a tag.
+#
+# `podo deploy` consumes images; it does not build them. This is the other half:
+# tagging a commit produces the two images that `podo deploy apply` then rolls out.
+# It stops at the push, because rolling out requires confirming a plan hash and that
+# approval belongs to a person.
+#
+# ── Which runner, and what it costs ──────────────────────────────────────────────
+#
+# GitHub-hosted runners are free for PUBLIC repositories only. In a PRIVATE
+# repository every minute is metered against the account's included Actions minutes
+# and billed beyond them -- and image builds are the most expensive job most
+# projects run. A self-hosted runner consumes no Actions minutes at all, whatever
+# the repository's visibility.
+#
+# So the runner is a variable rather than a constant:
+#
+#   PODOKIT_RUNNER   repository or organization variable, a JSON array of labels.
+#                    Unset -> ["ubuntu-latest"], which is right for a public
+#                    repository and costs money in a private one.
+#                    Self-hosted example: ["self-hosted","Linux","X64"]
+#
+# Set it before the first tag if this repository is private. Nothing here warns you
+# when you have not: the workflow succeeds either way, and the difference shows up
+# on a bill.
+#
+# ── The other two variables ──────────────────────────────────────────────────────
+#
+#   PODOKIT_DEPLOY_PROFILE   which .podokit/deploy/<name>.json names the image
+#                            repositories. Unset -> production.
+#   PODOKIT_IMAGE_PLATFORM   the architecture the deployment target runs.
+#                            Unset -> linux/amd64. Building for the wrong one
+#                            produces "exec format error" at rollout, after the
+#                            migration has already run.
+#
+# ── Secrets ──────────────────────────────────────────────────────────────────────
+#
+#   REGISTRY_USERNAME / REGISTRY_PASSWORD   credentials for the registry named by
+#   the profile. A robot or deploy account is enough, but note that some registries
+#   refuse to let a robot CREATE a repository -- push the first tag of a new
+#   repository with an account that can, or create it in the registry first.
+
+name: release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  images:
+    # One job builds both images rather than a matrix of two. A self-hosted pool is
+    # usually small, and fanning out here takes runners away from every other
+    # repository that shares it for no wall-clock gain on a multi-core machine.
+    runs-on: ${{ fromJSON(vars.PODOKIT_RUNNER || '["ubuntu-latest"]') }}
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci --no-audit --no-fund
+
+      # Verify before publishing. An image built from a commit that never passed is
+      # indistinguishable from one that did, once it is in the registry.
+      - run: npm run lint
+      - run: npm test
+
+      - name: Read the release target from the deployment profile
+        id: profile
+        run: |
+          node --input-type=module -e '
+            import { readFileSync } from "node:fs";
+            const name = process.env.PROFILE || "production";
+            const path = `.podokit/deploy/${name}.json`;
+            let profile;
+            try {
+              profile = JSON.parse(readFileSync(path, "utf8"));
+            } catch {
+              throw new Error(`No deployment profile at ${path}. Run podo deploy init first.`);
+            }
+            const { apiRepository, webRepository } = profile.release ?? {};
+            if (!apiRepository || !webRepository) {
+              throw new Error(`${path} does not declare release.apiRepository and release.webRepository.`);
+            }
+            // Everything before the first slash is a registry host only when it
+            // looks like one; otherwise the reference is a Docker Hub short name.
+            const first = apiRepository.split("/")[0];
+            const registry = /[.:]/.test(first) ? first : "";
+            const out = [
+              `api=${apiRepository}`,
+              `web=${webRepository}`,
+              `registry=${registry}`,
+              `tag=${process.env.GITHUB_REF_NAME}`,
+            ].join("\n");
+            process.stdout.write(out + "\n");
+          ' >> "$GITHUB_OUTPUT"
+        env:
+          PROFILE: ${{ vars.PODOKIT_DEPLOY_PROFILE }}
+
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ${{ steps.profile.outputs.registry }}
+          username: ${{ secrets.REGISTRY_USERNAME }}
+          password: ${{ secrets.REGISTRY_PASSWORD }}
+
+      - name: Build and push the API image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: apps/api/Dockerfile
+          platforms: ${{ vars.PODOKIT_IMAGE_PLATFORM || 'linux/amd64' }}
+          push: true
+          tags: ${{ steps.profile.outputs.api }}:${{ steps.profile.outputs.tag }}
+          cache-from: type=gha,scope=api
+          cache-to: type=gha,scope=api,mode=max
+
+      - name: Build and push the web image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: apps/web/Dockerfile
+          platforms: ${{ vars.PODOKIT_IMAGE_PLATFORM || 'linux/amd64' }}
+          push: true
+          tags: ${{ steps.profile.outputs.web }}:${{ steps.profile.outputs.tag }}
+          cache-from: type=gha,scope=web
+          cache-to: type=gha,scope=web,mode=max
+
+      - name: Report what to deploy
+        run: |
+          echo "Pushed ${{ steps.profile.outputs.api }}:${{ steps.profile.outputs.tag }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "Pushed ${{ steps.profile.outputs.web }}:${{ steps.profile.outputs.tag }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo 'Roll out with `podo deploy plan --profile <name> --release ${{ steps.profile.outputs.tag }}`, then apply the printed hash.' >> "$GITHUB_STEP_SUMMARY"