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.

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

Run the dry-run first. The CLI selects a cloud overlay from the registered provider unless --cloud overrides it.

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 the URL with its public control-plane API URL. A user role and the bearer token scope must both authorize an operation. After a platform release adds scopes to the device flow, use astro auth refresh to mint an access token carrying the new scope.

Register and manage a tenant cluster¶

Open Admin → 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 explicit operator commands:

astro operator cluster install-agent --slug <cluster-slug>
astro operator cluster deploy-agent --slug <cluster-slug>

The install command issues a one-time cluster agent key and writes it directly through kubectl; it does not print the raw key.

Connect source control¶

Open Admin → Providers → Source and create or authorize a source connection. Astrolift supports different connection modes per host, including GitHub App/OAuth and token-based connections.

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 Register App in the sidebar, 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]]
slug = "web"
kind = "deployment"
replicas = 1

[workloads.containers.app]
image = "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

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

Use the app's Deployments page to inspect the Astrolift state rather than assuming the source CI job implies a successful rollout. 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.