platform>docssolutionspricingcontact

Local development

Preview URLs, agent addressing, and catalog-backed auth when hacking on Zectre locally.

How the proxy picks a backend (Host → deployment)

zectre-proxy resolves an incoming host in this order (see zectre-proxy cold_start):

  1. deployments.preview_url — canonical match on the first host label; stale routes.deployment_id must not override it.
  2. Pinned route — a routes row for this domain with deployment_id set.
  3. Latest route — a routes row for this domain with deployment_id NULL (points at the current app/env).
  4. Legacy app subdomain — applications.subdomain fallback.

Deploy and API handlers maintain routes and deployment metadata so the proxy’s view stays consistent as rollouts happen.

Agent address_override

The proxy connects to tasks at {node.address}:{task.port}. If the agent advertises an address your proxy cannot reach (common in Docker or multi-NIC setups), set address_override in agent config.

SetupSymptomFix
All services on one machineProxy tries LAN IP, connection refusedaddress_override = "127.0.0.1"
Proxy in Docker, agent on host127.0.0.1 inside container is wronghost.docker.internal or host LAN IP
Agent on VMHost cannot reach guest IPOverride to an IP reachable from the proxy

Without a correct override you may see 502 responses, X-Error-Detail mentioning connection failures, or failed health checks.

Catalog + cluster JWT (recap)

  1. Create DB for catalog; set GitHub OAuth env vars.
  2. Run catalog migrations (often at startup).
  3. In platform config [auth], set catalog_jwks_url, jwt_expected_iss, and jwt_expected_aud to match the catalog and API.
  4. Dashboard: follow zectre-platform/dashboard/.env.example — catalog mode changes which API base the UI uses (see Dashboard).
  5. CLI: ZECTRE_CATALOG_URL then zectre login.

See Auth & catalog for the conceptual map.