Skip to content

Anatomy of a Deploy (end-to-end)

The single thread that ties every component together:

  1. Sign up & set up — User logs in via GitHub or Google SSO, creates a workspace, then a project with a default region — each service is placed per environment, defaulting there (FR-077) — installs the Starform GitHub App, and connects a repo. (§13, §15, §20.1)
  2. Push — A push to a configured branch fires a GitHub webhook to the Starbase API, which verifies the signature, deduplicates, debounces rapid pushes, and enqueues a build job. (§16.11)
  3. Build — Starbase Worker clones the source; Railpack detects the framework (or a Dockerfile is used as fallback) and the build runs on Depot (one isolated Depot project per workspace); the image is pushed to the placement region's DO Container Registry; build logs relay live to the dashboard and archive to DO Spaces. (§16)
  4. Desired state — Worker records the new image and updates the project's desired state. (§32)
  5. Apply — Shuttle, running in the project's cluster, pulls desired state every 30s, diffs it against the live cluster, and applies the per-project resource set (namespace, isolation policies, Var Group Secrets, Deployment, Service, HTTPRoute, etc.) as a zero-downtime rolling update. (§19, §20)
  6. Serve traffic — Cloudflare → DO Load Balancer → Envoy Gateway (routes by hostname via HTTPRoute) → the customer pod. (§5, §33, §34)
  7. Observe — one OTel Collector per cluster ships app logs, Envoy access logs, and cAdvisor metrics to the regional OTel gateway → ClickHouse (per-plan TTL retention); Stardeck shows logs and the seven customer metrics — SQL over the rows, scoped per-tenant by a server-side query filter. (§35 v2)
  8. Bill — Shuttle snapshots running pods every 60s to Starbase (Postgres raw snapshots + running totals; the ClickHouse audit trail is post-MVP); a monthly cron applies the plan credit and generates a Stripe invoice. (§36)

Core principle

Starbase decides, Shuttle applies. Everything flows through desired state — there is no direct Kubernetes mutation outside the desired-state loop.

How the §-cross-references work (the load-bearing bit)

This site is reorganized by component, so the PRD's old linear §-numbers no longer map to a single document. Referential integrity is preserved three ways:

  • Stable anchors. Every section keeps a §-encoded anchor, independent of its page or title — e.g. the tenant key lives at §24.1 and the desired-state contract at §32. Those links are live right now.
  • One directory. Canonical Sources records the one page each § lives on. If a section is ever re-homed, only that table changes — the anchor doesn't.
  • Strict build. mkdocs build --strict turns any broken §-link into a build failure, so drift can't sneak in.

Plain-text §-citations above (e.g. §16, §32) become live links as their pages land in Phase 2.