Skip to content

armgit / qm

Public Imported from GitHub
0

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.md
index 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.md
new file mode 100644
index 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.ts
index 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"],