Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

feat: Porter deployment onboarding — checklist, deploy reference, guardrails

Josh France93ac1c93e153
diff --git a/.codex/skills/deploy-qm/references/porter.md b/.codex/skills/deploy-qm/references/porter.md
new file mode 100644
index 000000000..4a1b96704
--- /dev/null
+++ b/.codex/skills/deploy-qm/references/porter.md
@@ -0,0 +1,5 @@
+# Porter deployment
+
+Read
+[`../../../../cli/templates/deployment/references/porter.md`](../../../../cli/templates/deployment/references/porter.md)
+completely and follow it.
diff --git a/cli/src/secrets.ts b/cli/src/secrets.ts
index ae6585065..d0291789e 100644
--- a/cli/src/secrets.ts
+++ b/cli/src/secrets.ts
@@ -137,7 +137,10 @@ export const FIRST_PARTY_SECRET_SPECS: readonly SecretSpec[] = [
],
},
},
- description: "Porter API token for the sandbox backend and the per-deployment app publisher.",
+ description:
+ "Admin-role Porter API token for the sandbox backend and the per-deployment app publisher — Developer-role tokens fail mid-deployment with PERMISSION_DENIED.",
+ generate:
+ "create an Admin-role API token in the Porter dashboard (https://dashboard.porter.run → Settings → API tokens)",
},
{
name: "SPRITES_TOKEN",
diff --git a/cli/templates/deployment/deployment.md b/cli/templates/deployment/deployment.md
index 857129e32..7b8cbacb3 100644
--- a/cli/templates/deployment/deployment.md
+++ b/cli/templates/deployment/deployment.md
@@ -15,9 +15,12 @@ Before cloud mutation, read `qm.config.jsonc` when it exists. Its `target` is
the selected provider; confirm it with the operator and do not offer to change
it in place. If the repository has not been initialized, collect:
-- hosting target: a cloud provider, Fly.io or AWS. Recommend Fly.io when the
- operator has no preference. The docker target runs everything on the local
- machine, is for a quick local test drive only, and is outside this
+- hosting target: a cloud provider — Fly.io, AWS, or Porter. Recommend Fly.io
+ when the operator has no preference. Porter deploys onto a Kubernetes
+ cluster in the operator's own cloud account and has no `qm` CLI target:
+ choosing it switches this workflow to `references/porter.md`, which drives
+ the Porter CLI and dashboard directly. The docker target runs everything on
+ the local machine, is for a quick local test drive only, and is outside this
workflow; never present it as the recommended path for a real deployment;
- the first administrator's verified work email;
- how people sign in: the built-in `auth` broker, which emails a one-time link,
diff --git a/cli/templates/deployment/references/porter.md b/cli/templates/deployment/references/porter.md
new file mode 100644
index 000000000..1ffa8be17
--- /dev/null
+++ b/cli/templates/deployment/references/porter.md
@@ -0,0 +1,73 @@
+# Porter deployment
+
+Use this after the choices and billing confirmation in `deployment.md`. Porter
+has no `qm` CLI target: `setup`, `plan`, and `up` do not drive it. The flow is
+the Porter CLI plus the repo's `porter/apps/` templates, with `docs/porter.md`
+as the reference for every failure mode named below.
+
+## Preflight
+
+Install the [Porter CLI](https://docs.porter.run/cli/installation) and prefer
+it over raw API calls wherever a command exists. Require Docker Buildx too —
+every image must be built `--platform linux/amd64`:
+
+```bash
+porter auth login
+porter config set-project <project-id>
+docker buildx version
+```
+
+Three dashboard steps come before any cluster, in this order. Do them through
+the operator's browser when you have browser access; otherwise give the
+operator the exact URL and wait:
+
+1. **Cloud account.** A cloud account must be linked to the Porter project at
+ <https://dashboard.porter.run/cloud-accounts>. Check before prompting: with
+ a token, `GET <PORTER_DEPLOY_URL>/api/v2/alpha/projects/<project>/cloud-accounts`
+ lists linked accounts and their connection state. If none is connected, the
+ operator links one themselves — the flow grants Porter IAM roles via a
+ CloudFormation stack (or the Azure/GCP equivalent) in their own cloud
+ console, and no agent should drive that unattended. Field gotchas: the AWS
+ quick-create link opens in `us-east-2`, so a region-pinning SCP fails the
+ stack with an explicit deny (reopen the same URL under the permitted
+ region), and the account ID Porter wants is the one in the AWS console's
+ top-right menu, not whatever the operator's CLI is logged into.
+2. **Admin API token.** Mint an **Admin-role** token under Settings → API
+ tokens and record `PORTER_DEPLOY_PROJECT_ID` and `PORTER_DEPLOY_CLUSTER_ID`.
+ A Developer token survives every read and then dies mid-deployment with
+ `PERMISSION_DENIED`, and cannot delete clusters — check the role before
+ provisioning anything the operator will later need to remove.
+3. **Cluster contract.** Create the cluster with the sandbox load balancer,
+ `sandboxesEnabled`, and the apps root domain already in the creation
+ contract (`docs/porter.md` → "Giving published apps stable hostnames").
+ Attaching them after creation is the wedged-cluster path.
+
+## Configure the administrator before first boot
+
+The workflow's step 1 collected the administrator's email; on Porter nothing
+derives the env vars from it, so set them by hand on core before the first
+apply:
+
+```bash
+ADMIN_GRANTS=<email>:org_admin
+AUTH_ALLOWED_EMAILS=<email>
+```
+
+With Postgres and no `ADMIN_GRANTS`, the instance boots, sign-in works, and
+the admin console is permanently unreachable — there is no in-product way to
+grant the first admin afterwards. The Helm chart bridges `AUTH_ALLOWED_EMAILS`
+to the portal's `OIDC_ALLOWED_EMAILS`; on the raw `porter/apps/` path set both.
+
+## Build, deploy, verify
+
+```bash
+for f in porter/apps/*.yaml; do porter apply -f "$f"; done
+```
+
+Apply runs once per app file, twice overall — assigned hostnames land on the
+second pass. Then hand-wire the six service URLs per the table in
+`docs/porter.md` ("Hosting the qm surfaces"), push secrets as Porter env
+groups, and verify by signing in as the administrator and opening the Admin
+tab. Published-app serving needs nothing further: apps are reachable
+signed-in at `/d/<app>/`; setting `DEPLOY_APPS_DOMAIN` upgrades them to
+per-app subdomains (`docs/porter.md`, onboarding checklist).
diff --git a/cli/test/package.test.ts b/cli/test/package.test.ts
index e4b9c0e06..461171622 100644
--- a/cli/test/package.test.ts
+++ b/cli/test/package.test.ts
@@ -285,6 +285,7 @@ else if (command === "secretsmanager get-secret-value") {
assert.ok(packed[0]!.files.some(({ path }) => path === "templates/aws/microvm-agent/agent.mjs"));
assert.ok(packed[0]!.files.some(({ path }) => path === "templates/deployment/deployment.md"));
assert.ok(packed[0]!.files.some(({ path }) => path === "templates/deployment/references/fly.md"));
+ assert.ok(packed[0]!.files.some(({ path }) => path === "templates/deployment/references/porter.md"));
assert.ok(packed[0]!.files.some(({ path }) => path === "templates/fly/core.toml"));
assert.ok(!packed[0]!.files.some(({ path }) => path === "src/contract.ts" || path === "bin/qm.ts"));
} finally {
diff --git a/docs/porter.md b/docs/porter.md
index fb95bec40..290081ac2 100644
--- a/docs/porter.md
+++ b/docs/porter.md
@@ -10,11 +10,54 @@ AWS, GCP, or Azure account. qm can use it two ways, independently:
Both need a Porter API token and the project and cluster that own the sandbox API:
```bash
-PORTER_DEPLOY_API_TOKEN=<api token from Settings -> API tokens>
+PORTER_DEPLOY_API_TOKEN=<ADMIN-role api token from Settings -> API tokens>
PORTER_DEPLOY_PROJECT_ID=<project id>
PORTER_DEPLOY_CLUSTER_ID=<cluster id>
```
+## Onboarding checklist
+
+Everything below this section is reference and field notes; this is the order that
+actually gets a new operator from zero to a working instance (the deployment workflow's
+agent-facing version lives at `cli/templates/deployment/references/porter.md`). If you are an agent doing
+this deployment: install and prefer the `porter` CLI over raw API calls wherever a
+command exists ([install instructions](https://docs.porter.run/cli/installation)); use
+the operator's browser for the dashboard steps when you have browser access, and
+otherwise hand the operator the exact URL and wait — several steps below cannot be done
+any other way.
+
+1. **A cloud account must be linked to the Porter project** at
+ [dashboard.porter.run/cloud-accounts](https://dashboard.porter.run/cloud-accounts)
+ before any cluster can exist. Check first — with a token,
+ `GET <PORTER_DEPLOY_URL>/api/v2/alpha/projects/<project>/cloud-accounts` lists linked
+ accounts and their connection state; without one, look at the dashboard page. If none
+ is connected, the operator has to link one themselves: the flow grants Porter IAM
+ roles via a CloudFormation stack (or the Azure/GCP equivalent) in _their_ cloud
+ console, which no agent should drive unattended. Two AWS gotchas from the field: the
+ quick-create link opens in `us-east-2`, so an org SCP that pins regions makes the
+ stack fail with an explicit deny — reopen the same URL under the permitted region —
+ and the account ID Porter wants is the one shown in the AWS console's own top-right
+ menu, not whatever account the operator's CLI happens to be logged into.
+2. **Mint an Admin-role API token** (Settings → API tokens) and record
+ `PORTER_DEPLOY_PROJECT_ID` and `PORTER_DEPLOY_CLUSTER_ID`. The role matters: a
+ Developer token survives every read until it dies mid-deployment with
+ `PERMISSION_DENIED` (details under egress below) and cannot delete clusters. Check
+ the role before provisioning anything you will later need to remove.
+3. **Create the cluster with the sandbox load balancer in the creation contract** —
+ sandbox ingress, `sandboxesEnabled`, and the apps root domain all belong in the
+ contract the cluster is born with; attaching them later is the wedged-cluster
+ forensics that "Giving published apps stable hostnames" below exists to debug.
+4. **Name the administrator before first boot.** Set `ADMIN_GRANTS=<email>:org_admin`
+ on core and the sign-in allowlist (`AUTH_ALLOWED_EMAILS=<email>` — the Helm chart
+ bridges it to the portal's `OIDC_ALLOWED_EMAILS`). This is the step the old docs
+ never mentioned: with Postgres and no `ADMIN_GRANTS`, the instance boots, everyone
+ allowed can sign in, and the admin console is permanently unreachable — there is no
+ in-product way to grant the first admin afterwards.
+5. **Build, push, and apply**: images built `--platform linux/amd64`, then
+ `for f in porter/apps/*.yaml; do porter apply -f "$f"; done` (twice — the hostname
+ lands on the second pass), then wire the service URLs per the table below. Verify by
+ signing in as the admin and opening the Admin tab.
+
## Hosting the qm surfaces
`porter/apps/` declares the six services (core, auth, web-ui, admin, portal,
diff --git a/src/index.ts b/src/index.ts
index 817889b5c..34eaa49d1 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -44,6 +44,12 @@ if (config.deployAppsDomain) {
});
}
+if (config.databaseUrl && !config.adminGrants) {
+ console.warn(
+ "[qm] ADMIN_GRANTS is unset with a durable store — if this deployment has never named an admin, the admin console is unreachable and cannot be unlocked from inside the product; set ADMIN_GRANTS=<email>:org_admin (ignore this if an admin was already promoted in the Users tab).",
+ );
+}
+
if (config.deployProvider === "docker") {
void dockerDaemonFailure().then((failure) => {
if (failure)
diff --git a/test/deployment-skill.test.ts b/test/deployment-skill.test.ts
index 4ef25e261..efc0a7f5d 100644
--- a/test/deployment-skill.test.ts
+++ b/test/deployment-skill.test.ts
@@ -11,7 +11,7 @@ test("package-consumer deployment skill covers both self-owned providers and the
const root = read("cli/templates/deployment/deployment.md");
for (const phrase of [
"Before cloud mutation",
- "Fly.io or AWS",
+ "Fly.io, AWS, or Porter",
"deployment repository",
"npm ci",
"slack render",
@@ -36,6 +36,7 @@ test("package-consumer deployment skill covers both self-owned providers and the
".codex/skills/deploy-qm/agents/openai.yaml",
".codex/skills/deploy-qm/references/fly.md",
".codex/skills/deploy-qm/references/aws.md",
+ ".codex/skills/deploy-qm/references/porter.md",
".codex/skills/deploy-qm/references/slack.md",
".codex/skills/deploy-qm/references/email.md",
]) {
@@ -47,6 +48,7 @@ test("package-consumer deployment skill covers both self-owned providers and the
"cli/templates/deployment/SKILL.md",
"cli/templates/deployment/references/fly.md",
"cli/templates/deployment/references/aws.md",
+ "cli/templates/deployment/references/porter.md",
"cli/templates/deployment/references/slack.md",
"cli/templates/deployment/references/email.md",
]) {
@@ -77,6 +79,27 @@ test("the deploy skill tells an agent where the sign-in email transport comes fr
);
});
+test("the porter reference walks the dashboard steps an agent cannot skip", () => {
+ const porter = read("cli/templates/deployment/references/porter.md");
+ for (const phrase of [
+ "dashboard.porter.run/cloud-accounts",
+ "Admin-role",
+ "PERMISSION_DENIED",
+ "ADMIN_GRANTS",
+ "AUTH_ALLOWED_EMAILS",
+ "porter apply",
+ "linux/amd64",
+ ]) {
+ assert.ok(porter.includes(phrase), `porter reference covers ${phrase}`);
+ }
+ assert.match(porter, /operator links one themselves/, "cloud-account linking is called out as the operator's step");
+ assert.match(read("cli/templates/deployment/deployment.md"), /references\/porter\.md/);
+ assert.match(
+ read(".codex/skills/deploy-qm/references/porter.md"),
+ /cli\/templates\/deployment\/references\/porter\.md/,
+ );
+});
+
test("connector onboarding is governed by the live admin-configured list", () => {
const onboarding = read("plugins/onboarding/skills/onboarding/SKILL.md");
const connectApps = read("skills-seed/connect-apps/SKILL.md");