docs(self-hosting): close GKE guide gaps from infra #495

Merged
AG
3d ago
+155-21

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 itemWhere it landed here
Desktop feed bucket only once the signing key existsinstall-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 .tgzStep 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 warningStep 14, and Troubleshooting › Expected during the install
502 on closed paths (edge-deny backend) is intendedStep 14 list, and Troubleshooting › Expected during the install
first-admin.sh API_HOST and PASSWORD_FILEServed script updated; step 15 documents both; agent note: never read the password file

Left out, on purpose

  • helm dependency build for installing from a checkout: the website guide installs only the released .tgz (step 11 and 13 use release/agent-relay-0.7.54.tgz); it never tells a reader to install the chart from the infra checkout. The checkout half of #495's pins note is left out for the same reason.
  • desktop_feed_has_signing_keys: exists only on infra main after #495, not in agent-relay-2026.11.16, which this guide pins. The Troubleshooting entry says the pinned Terraform has no such setting and gives the jq recovery 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, then check: selfhost-files: up to date (exit 0)
  • npm test: 637 + 319 passed; npm run lint: exit 0; npm run typecheck: exit 0
  • shellcheck and bash -n on first-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
  • jq line from step 7 run against the agent-relay-2026.11.16 release manifest: prints the same digests the guide pins

🤖 Generated with Claude Code


Autofix with [code]smith
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_name unset during install; enabling storage without the signing key makes relay-control exit repeatedly. Adds a Troubleshooting entry with a jq recovery, and warns not to rerun helm upgrade until the key exists.
  • Version pins: documents that SERVICES_IMAGE, PSQL_IMAGE, and agent-relay-0.7.54.tgz belong to release agent-relay-2026.11.16 and 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 BackendConfig warning is harmless, and that 502 on closed paths is expected when no Cloud Armor policy is set.
  • first-admin.sh: adds optional API_HOST and PASSWORD_FILE; the password can now be kept in a local file instead of Secret Manager. SHA256SUMS and the downloads table updated.