docs(self-hosting): close GKE guide gaps from infra #495
Merged
AG
3d ago+155+155+012345678901234567890123456789-21-21-01234567890123456789
Mirrors AgentWorkforce/infra#495 into the website's GKE guide. Merge after infra#495: the served first-admin.sh is a copy of infra's at the #495 head (1e4692a2), with the website's own comment line 2 kept.
What changed
| #495 item | Where it landed here |
|---|---|
| Desktop feed bucket only once the signing key exists | install-gke.md step 4 (leave desktop_feed_bucket_name out during the install, the error it causes); feed section item 1 (don't rerun helm upgrade until item 3); new Troubleshooting section relay-control exits: signer and storage must be set together with the jq 'del(.["relay-control"].extraEnv)' recovery |
Pinned SERVICES_IMAGE, PSQL_IMAGE, chart .tgz | Step 7: they belong to agent-relay-2026.11.16 (chart 0.7.54); how to read them from another release's release/release-manifest.json, and infra/releases/<tag>/pins.json for the services image |
Ingress 15 to 20 minutes, harmless Translation failed ... no BackendConfig warning | Step 14, and Troubleshooting › Expected during the install |
| 502 on closed paths (edge-deny backend) is intended | Step 14 list, and Troubleshooting › Expected during the install |
first-admin.sh API_HOST and PASSWORD_FILE | Served script updated; step 15 documents both; agent note: never read the password file |
Left out, on purpose
helm dependency buildfor installing from a checkout: the website guide installs only the released.tgz(step 11 and 13 userelease/agent-relay-0.7.54.tgz); it never tells a reader to install the chart from theinfracheckout. The checkout half of #495's pins note is left out for the same reason.desktop_feed_has_signing_keys: exists only on inframainafter #495, not inagent-relay-2026.11.16, which this guide pins. The Troubleshooting entry says the pinned Terraform has no such setting and gives thejqrecovery instead. Add the variable when the guide moves to a release that has it.- #495's teardown line ("with
PASSWORD_FILE, delete that file"): the website teardown page doesn't cover the first-admin secret today, so there is no matching line.
Checks
node scripts/selfhost-files.mjs write, thencheck:selfhost-files: up to date(exit 0)npm test: 637 + 319 passed;npm run lint: exit 0;npm run typecheck: exit 0shellcheckandbash -nonfirst-admin.sh: clean- infra's
scripts/selfhost/tests/gcp-first-admin-test.sh(at the #495 head) run against this repo's copy: all passed jqline from step 7 run against theagent-relay-2026.11.16release manifest: prints the same digests the guide pins
🤖 Generated with Claude Code
![Autofix with [code]smith](https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark-3x.png)
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.
Summary by cubic
Syncs the GKE self-hosting guide and its first-admin.sh script with the fixes from infra#495, so the install docs no longer steer readers into failures.
- Desktop feed bucket: the guide now says to leave
desktop_feed_bucket_nameunset during install; enabling storage without the signing key makes relay-control exit repeatedly. Adds a Troubleshooting entry with ajqrecovery, and warns not to rerunhelm upgradeuntil the key exists. - Version pins: documents that
SERVICES_IMAGE,PSQL_IMAGE, andagent-relay-0.7.54.tgzbelong to releaseagent-relay-2026.11.16and how to read the correct ones for a different release. - Ingress behavior: notes the 15–20 minute address wait, that a one-off
Translation failed ... no BackendConfigwarning is harmless, and that 502 on closed paths is expected when no Cloud Armor policy is set. first-admin.sh: adds optionalAPI_HOSTandPASSWORD_FILE; the password can now be kept in a local file instead of Secret Manager. SHA256SUMS and the downloads table updated.