Skip to content

Installing Astrolift

This page summarizes the install paths and points at the canonical runbooks. The runbooks live in astrolift-opscode because they walk Terraform + Helm files in that repo step-by-step.

At a glance

                          ┌─ AWS         → INSTALL-aws.md
Pick your cloud  ─────────┼─ GCP         → INSTALL-gcp.md
                          ├─ Azure       → INSTALL-azure.md
                          └─ vanilla k8s → INSTALL-k8s-native.md  (kind dev or bare-metal)

Prerequisites (all paths)

Tool Min version
Terraform 1.5 (1.9 used in CI)
Helm 3.16
kubectl 1.28
astro CLI latest

Cloud paths additionally need the cloud's CLI (aws / gcloud / az) and an account with provisioning permissions. See each runbook's prerequisites section.

Install flow (every path)

  1. Configure the cloud's config.env with your project slug + region
  2. Bootstrap state — one-time backend (S3 + DynamoDB / GCS bucket / Azure Storage Account)
  3. Plan + review — ./run.sh plan <cloud> <env>. Read the plan; never apply blind
  4. Apply — provisions VPC, cluster, datastores, identity, registry, observability + backup wiring
  5. Verify — ./<cloud>/scripts/cold-boot.sh <env> (AWS) or the matching script per cloud
  6. Build the env file — ./<cloud>/scripts/build-env.sh <env> pulls Terraform outputs + live secret values into a .env file the Helm install reads
  7. Helm install the control plane — helm install astrolift ./helm/astrolift -f ./helm/astrolift/values.<cloud>.yaml
  8. Register the cluster — use Admin → Clusters → Register. The currently released CLI has cluster bootstrap and keep-alive-agent operations, but does not expose cluster registration as astro cluster register.
  9. Deploy a first app — create a manifest with astro app init, register it with astro app register, then deploy a built image with astro app deploy --image-tag <ref>.

The runbooks in astrolift-opscode walk each step concretely. Run astro <command> --help against the CLI version distributed by the target control plane before copying commands into automation.

Multi-environment

Each cloud's <cloud>/environments/{dev,stg,prd}/ is independent — no cross-env state. Defaults follow a dev=light / stg=most / prd=full ladder for optional components. The toggle reference is in each cloud's variables.tf and summarized in INSTALL-aws.md § Toggle reference.

Multi-install (multi-region or multi-cloud)

A single Astrolift install owns one DNS zone + one database. To run in multiple regions or clouds, create independent installs — one per region/cloud — each with its own Terraform state, control plane, and cluster set. There is no master above them; cross-install coordination is per-flow.

What happens after install

  • The platform exposes the dashboard at https://<base-zone> (or the ingress hostname you configured)
  • App developers register apps via the astro CLI or the dashboard; see Getting Started for the dev side
  • Tenant deploys land in <org>-<app> namespaces on the registered tenant cluster(s)
  • Logs / metrics / traces flow to whichever observability backend the install was configured for (per-tenant routing supported)

Status

See astrolift-opscode/STATUS.md for the canonical state map — what's complete, what's partial, what's stub. Read this before reporting "X is broken" — it might be a tracked TODO.