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 (pinned to one cluster at creation), 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 DO Container Registry; build logs stream to ClickHouse. (§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 — Fluent Bit ships logs to the regional Vector aggregator → ClickHouse; vmagent scrapes Envoy + cAdvisor + kube-state-metrics and writes metrics to VictoriaMetrics; Stardeck shows logs and the seven customer metrics, scoped per-tenant by a server-side query filter. (§35)
  8. Bill — Shuttle snapshots running pods every 60s to Starbase (Postgres running totals + ClickHouse audit trail); 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 metrics attribution at §35.2. 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.