Multiplayer agent harness for work.
Document the two Porter hosting paths and warn on a missing apps domain
Josh Franceea842a9265a1
diff --git a/README.md b/README.mdindex aa34ab320..d18b2b7eb 100644--- a/README.md+++ b/README.md@@ -176,6 +176,7 @@ messages, and screenshots for organization identifiers before it pushes. Nothing- [`docs/getting-started.md`](./docs/getting-started.md) — first run, end to end- [`cli/README.md`](./cli/README.md) — the `qm` CLI and the deployment directory contract- [`docs/deploy-directory.md`](./docs/deploy-directory.md) — the deployment directory in full+- [`docs/porter.md`](./docs/porter.md) — running qm on Porter- [`.env.example`](./.env.example) — every knob, documented in place- [`plugins/`](./plugins) — the surfaces (Slack, web UI, admin, portal)diff --git a/docs/porter.md b/docs/porter.mdnew file mode 100644index 000000000..8e9f794b9--- /dev/null+++ b/docs/porter.md@@ -0,0 +1,67 @@+# Running qm on Porter++[Porter](https://porter.run) provisions and manages a Kubernetes cluster inside your own+AWS, GCP, or Azure account. qm can use it two ways, independently:++- `SANDBOX_BACKEND=porter` — every agent computer is a Porter sandbox with a persistent+ home volume.+- `DEPLOY_PROVIDER=porter` — apps the agent publishes run on the same cluster.++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_PROJECT_ID=<project id>+PORTER_DEPLOY_CLUSTER_ID=<cluster id>+```++## Hosting the qm surfaces++`porter/porter.yaml` declares the six services (core, auth, web-ui, admin, portal,+egress-proxy) as Porter apps built from `deploy/*/Dockerfile`:++```bash+porter apply -f porter/porter.yaml+```++Porter builds the images, runs the services, and assigns each web service a hostname, so+this path needs no DNS record, no TLS certificate, and no ingress controller. Set the+service secrets from the Porter dashboard or `porter apply`'s env-group support, and use+the portal's assigned hostname as `PUBLIC_WEB_URL`.++`deploy/helm/` carries the same topology as a Helm chart for operators who would rather+manage the release themselves; it expects the images published at+`ghcr.io/yc-software/qm/<service>` and an ingress you configure.++## Giving published apps stable hostnames++Apps the agent deploys are reachable only if the cluster gives them an address. Without+one, `apply` fails with `the cluster assigned no hostname`, and core warns at startup.++Point a wildcard DNS record at the cluster's ingress load balancer and name it:++```bash+PORTER_DEPLOY_APPS_DOMAIN=apps.example.com # *.apps.example.com -> cluster ingress+```++Each deployment then publishes at `<name>.apps.example.com`. Deployments are **private**+by default, matching the other providers; `PORTER_DEPLOY_VISIBILITY=public` opts a+deployment's domain into public ingress.++## Other knobs++| Variable | Meaning |+| -------------------------------------------------- | ---------------------------------------------------------------------------------- |+| `PORTER_DEPLOY_URL` | Porter API host, when it isn't `https://dashboard.porter.run` |+| `PORTER_SANDBOX_IMAGE` | Image agent computers boot from |+| `PORTER_DEPLOY_RUNNER_IMAGE` | Image published apps boot from (defaults to the sandbox image) |+| `PORTER_SANDBOX_EGRESS_PROXY_URL` | Forces sandbox traffic through the egress proxy; unset means no egress enforcement |+| `PORTER_SANDBOX_NAME_PREFIX` | Prefix for sandbox and app names on the cluster |+| `PORTER_DEPLOY_TTL_SEC` / `PORTER_SANDBOX_TTL_SEC` | Reap bodies after this long |++To QA a branch against a real Porter cluster before deploying it, the dev instance takes+the same backend:++```bash+bash scripts/dev-instance.sh up --sandbox porter+```diff --git a/src/config.ts b/src/config.tsindex a6cd62c58..98db43de6 100644--- a/src/config.ts+++ b/src/config.ts@@ -770,6 +770,11 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): Config {"[config] SANDBOX_BACKEND=porter without PORTER_SANDBOX_EGRESS_PROXY_URL — sandboxes run with NO egress enforcement (fail-open); set PORTER_SANDBOX_EGRESS_PROXY_URL to the egress proxy to force sandbox traffic through it.",);}+ if (env.DEPLOY_PROVIDER === "porter" && !env.PORTER_DEPLOY_APPS_DOMAIN) {+ console.warn(+ "[config] DEPLOY_PROVIDER=porter without PORTER_DEPLOY_APPS_DOMAIN — published apps only get a URL if the cluster assigns one, so a deploy can succeed with no reachable address; point a wildcard DNS record at the cluster ingress and set PORTER_DEPLOY_APPS_DOMAIN to give every app a stable hostname.",+ );+ }for (const [selected, label] of [[porterSandboxSelected, "SANDBOX_BACKEND=porter"],[env.DEPLOY_PROVIDER === "porter", "DEPLOY_PROVIDER=porter"],