Operator Quickstart¶

This page gives you the shortest honest paths to evaluate Astrolift. It does not promise a production platform in ten minutes: a real cloud install provisions databases, identity, networking, a control-plane runtime, and a tenant Kubernetes cluster.

Choose an evaluation path¶

Goal	Path
Inspect the dashboard and API locally	Run `astrolift-app`'s Compose development stack
Exercise Kubernetes prerequisites on a disposable cluster	Use the kind profile in `INSTALL-k8s-native.md`
Install an environment in AWS, GCP, or Azure	Use the matching `INSTALL-<cloud>.md` runbook

The canonical infrastructure status, including components that have not been exercised end-to-end in a live account, is astrolift-opscode/STATUS.md.

Local control-plane evaluation¶

From a checkout of astrolift-app:

./bootstrap.sh
./run.sh up
./run.sh seed
./run.sh urls

The local development URLs are:

dashboard: http://localhost:3000;
backend: http://localhost:8000/app/;
GraphQL: http://localhost:8000/app/gql/config/;
Temporal UI: http://localhost:8233;
Mailpit: http://localhost:8025.

Success check: ./run.sh ps lists every service as running and curl -s http://localhost:8000/health/ returns 200. If ./run.sh up fails before the backend starts, ./bootstrap.sh did not finish: it writes backend/config/local.env from backend/config/example.env; re-run it, it is safe to repeat.

Use ./run.sh logs, ./run.sh ps, and ./run.sh down to inspect or stop the stack. This is a source-development environment, not the supported production topology.

Kubernetes evaluation¶

For kind, bare metal, or an existing Kubernetes cluster, follow INSTALL-k8s-native.md. It is authoritative for the prerequisite chart, storage choices, control-plane values, and DNS setup.

The astro CLI can bootstrap the prerequisite chart after a cluster has been registered in the control plane:

astro cluster bootstrap \
  --cluster-slug <registered-cluster-slug> \
  --cloud k8s \
  --dry-run

astro cluster bootstrap \
  --cluster-slug <registered-cluster-slug> \
  --cloud k8s \
  --wait-timeout 10m

Substitute <registered-cluster-slug> with the slug you gave the cluster in Clusters → Register cluster. Run the dry-run first. The CLI selects a cloud overlay from the registered provider unless --cloud overrides it. The release lands in the astrolift-system namespace as astrolift-prereqs.

Success check:

helm -n astrolift-system list
kubectl -n astrolift-system get pods

astrolift-prereqs shows deployed and the pods reach Running. The most common failure is an authentication error on an exec_plugin cluster: refresh the operator kubeconfig first (aws eks update-kubeconfig --name <cluster> --region <region>, or the gcloud / az equivalent) and run the command again.

Configure the CLI¶

Install the CLI build distributed by your Astrolift install or release, then register the server and authenticate:

astro server add local http://localhost:8000
astro server use local
astro auth login local
astro auth status

For a deployed install, replace http://localhost:8000 with its public control-plane API URL (the global.platformDomain you set at Helm install). A user role and the sign-in scope must both authorize an operation. The default sign-in carries no cluster-operator permission: use astro auth login local --scope clusters for cluster bootstrap and agent installation, and --scope admin for platform-operator work (approved by the platform operator, valid 12 hours).

Success check: astro auth status shows the server and an active credential, and astro status answers. The refusal api token scope does not allow this permission means the sign-in scope is too narrow; sign in again with the scope above, adding a role cannot widen a sign-in.

Register and manage a tenant cluster¶

Open Clusters and select Register cluster. Supply:

a display name and stable slug;
an installed provider plugin;
region and Kubernetes API endpoint where required;
an authentication method (kubeconfig, service_account_token, or exec_plugin);
the method-specific JSON authentication configuration;
the ingress class.

Registration records and probes the cluster. Bring into management performs the managed lifecycle work after the prerequisites exist. Registration and management are separate states; an app cannot be registered against a merely recorded cluster.

For the keep-alive agent, use the operator commands:

astro operator cluster install-agent --slug <cluster-slug> --request-file agent-install.json
astro operator cluster agent-install-status --install-id <install-id>
astro operator cluster deploy-agent --slug <cluster-slug>

<cluster-slug> is the slug you registered; <install-id> is the installation UUID printed by install-agent. The install runs as a server-side workflow over the control plane's network: no local kubeconfig and no raw agent key. --request-file is a private file that retains the original request; retry with the same file after a lost reply. Acceptance is not health: agent-install-status reports heartbeat confirmation. These commands need --scope clusters. Details, including recovery, are in Install the cluster keep-alive agent.

Connect source control¶

Open Settings → Source providers and create or authorize a source connection. Astrolift supports different connection modes per host: an OAuth app or OAuth user connection, a GitHub App installation, or a personal access token, for GitHub, GitLab, Bitbucket and Gitea.

Use the callback URL shown by the UI for the chosen mode. Do not copy a callback path from an old guide: OAuth, GitHub App, and repository-webhook callbacks are different endpoints. After connecting, confirm the repository browser can list the repository you intend to register.

Register a first app¶

Open Apps → Register app, or prepare the repository with the CLI:

mkdir first-app && cd first-app
astro app init .

A minimal manifest has a top-level name and at least one workload:

name = "first-app"

[[workloads]]
name = "web"
kind = "deployment"
replicas = 1

[[workloads.containers]]
name = "app"
is_primary = true
image_ref = "ghcr.io/example/first-app:replace-me"
port = 8080

Replace the image with one your tenant cluster can pull. Then register the repository slice:

astro app register \
  --project-id <project-guid> \
  --source-repo owner/repository \
  --manifest-path astrolift.toml \
  --file astrolift.toml

<project-guid> comes from astro project list; owner/repository is the repository the source connection can list. Add --manifest-raw to register from the local file before a source connection exists.

Success check: astro app show first-app prints the app with its web workload. If registration reports the repository cannot be read, the source connection does not cover that repository; fix it under Settings → Source providers or register with --manifest-raw.

The dashboard wizard can fetch, validate, edit, and optionally push the manifest and managed CI workflow through the selected source connection.

Deploy and verify¶

The CLI deploy command deploys an already-built image:

astro app deploy \
  --app first-app \
  --env production \
  --image-tag ghcr.io/example/first-app:<immutable-tag-or-digest> \
  --wait

<immutable-tag-or-digest> is the tag or digest your CI pushed; --image-tag is required because the default build mode is ci_pushed. --wait exits 0 on success and 1 on a failed deployment. Use the app's Deployments page (/deployments/<id>) to inspect the Astrolift state rather than assuming the source CI job implies a successful rollout. An ImagePullBackOff on the pod means the tag was never published or the cluster cannot pull from the registry; see Image pull failure. Inspect current state and logs with:

astro app show first-app
astro app logs --app first-app --since 30m

Public URL and TLS behavior depend on the manifest, ingress provider, and DNS configuration. Follow the hostname and challenge records surfaced by the dashboard instead of assuming a fixed <app>.<base-domain> pattern.

Next steps¶

Working with apps covers secrets, bundles, configuration, deployments, and app controls.
Operator runbooks covers common cluster, rollout, teardown, and credential failures.
Installing Astrolift links the complete cloud runbooks.
Use astro <command> --help for the installed CLI's exact flags.