Install

The GantryCD backend is a single stateless Go binary with the web UI embedded. Run two or more replicas behind a load balancer; they coordinate through the database. This page gets a backend running; the runner side is in Runner groups.

What it needs

You provision these yourself — GantryCD does not create them. Both database schemas are declarative and must be applied before first boot; the chart README covers the migration image and hook workflows.

Ways to run it

Helm (recommended for production)

There’s a chart at charts/gantrycd. It does not create Postgres, Redis, or the buckets — create those and their Secrets first. Two reference value files get you started:

helm install gantrycd charts/gantrycd -f charts/gantrycd/values.self-hosted.yaml

A second chart, charts/gantrycd-runner-group-kubernetes, deploys a Kubernetes runner group. See the chart READMEs for the full knob list.

Docker

The backend ships as a container image. Build and push your own with make build_docker_backend (point IMAGE_PREFIXES at your registry), or run the published image with the environment supplied. The runner-group images (docker, github) ship the same way.

Binary

make build_artifacts_backend VERSION=v1.2.3 produces a static Linux binary (amd64/arm64) with a checksum sidecar, web UI embedded. The same target builds runner and CLI artifacts. Build details and release verification are in Building And Release Artifacts.

First boot

1. Apply the schema and start the backend with at least its core config (Configuration).

2. Configure at least one SSO provider so people can sign in (Single sign-on).

3. Bootstrap the first super-admin. There are no local accounts — sign in once so your user row exists, then from a host with database access:

   gantrycli operator users promote-super-admin --user-id=<your-user-id>

   Every later super-admin is managed from the Backstage admin UI (enable it with GANTRYCD_BACKEND_BACKSTAGE_ENABLED=true). GantryCD never auto-promotes from an env var or a login.

Background jobs

The backend runs scheduled jobs that keep the system healthy — stale-runner cleanup, queue recovery, status reconciliation, session/SSO housekeeping. They’re leader-elected, so running multiple replicas is safe and you don’t configure them. Their freshness (via background_job_schedules) is also how github-actions runner-group connection status is derived.

The async task queue is different and is the one place replica count buys you throughput: every replica runs GANTRYCD_TASK_PROCESSOR_CONCURRENCY (default 4) worker slots continuously, each holding one task at a time under an exclusive lease. Capacity is replicas x slots. A replica that dies has its in-flight tasks picked up by another once their leases lapse, which is that task type’s own ceiling plus 30 s — 5.5 minutes for most types, 10.5 for the resource-index and dependency-graph rebuilds, 30.5 for Explore diagnostics, and an hour and a half-minute for object-store prefix deletes (the per-type table is in Async Task Queue). A GRACEFUL rollout does not pay that: shutdown releases the leases explicitly, so another replica picks the work up within seconds. Behavior is documented in Deployment State Machine and Async Task Queue.

Local development

For a laptop setup with Docker Compose dependencies, follow the Quickstart instead — it’s the development path, not a production one.