Skip to content
GantryCD

Quickstart

This is the from-source path: it builds GantryCD locally and walks you to a running plan on your own machine. It’s the fastest way to kick the tires or to develop GantryCD itself.

To run GantryCD for real (published images, your own Postgres and S3, behind SSO), follow Install instead — you won’t need a Go toolchain there.

Prerequisites

Because this path compiles from source, you need a dev toolchain:

  • Go 1.25+, Node.js 20+
  • Docker + Docker Compose (for Postgres, Redis, and S3-compatible storage)
  • Atlas (declarative schema tool) and golangci-lint

Run everything from the repository root. Always use make targets rather than raw go commands.

1. Bring up dependencies

Postgres, Redis, and an S3-compatible store (RustFS) come from Compose; the schema is applied declaratively.

docker compose up -d
AUTO_APPROVE=1 make atlas_schema_apply

2. Start the backend and web UI

make run_backend   # API on :8080, metrics on :9090
make run_web        # dev server on http://localhost:5173

Check the backend is alive:

curl http://localhost:8080/health

3. Enable a login

GantryCD has no local accounts — every user is provisioned through SSO. The quickest provider for local dev is a GitHub OAuth app:

  1. Create a GitHub OAuth app with callback http://localhost:8080/api/v1/auth/sso/github/callback.

  2. Set GANTRYCD_SSO_GITHUB_CLIENT_ID and GANTRYCD_SSO_GITHUB_CLIENT_SECRET, then restart the backend.

  3. Sign in once at http://localhost:5173 so your user row is created, then promote yourself from a shell with database access:

    gantrycli operator users promote-super-admin \
  --user-id=github:<your-login>:<your-numeric-id>

Your GitHub numeric id is the id field at https://api.github.com/users/<your-login>. More providers and the full story are in Single sign-on.

4. Create a runner group

In the UI, go to Org settings → Runner groups and create a self-hosted group. Download the PEM private key it shows you once, and save it locally. Then start the local launcher, which runs ephemeral runners as child processes:

export RUNNER_GROUP_ID=<from the UI>
export RUNNER_PRIVATE_KEY_FILE=<path to the PEM you saved>
export BACKEND_URL=http://localhost:8080
make run_runner_group

The group should now show as connected in the UI. The other launchers (Docker, Kubernetes, GitHub Actions) are covered in Runner groups.

5. Create a stack and ship a plan

In the UI:

  1. Create a stack pointing at a repository, branch, and working directory that contain OpenTofu config.
  2. Sync the stack so GantryCD records the latest commit.
  3. Trigger a plan deployment.

You’ll watch the run get picked up by your runner group, stream its logs, and — if the plan has changes — pause at a confirmation step. Confirm it to apply.

That is the whole loop. From here:

Troubleshooting

  • No providers on the login page — both GANTRYCD_SSO_GITHUB_CLIENT_ID and _SECRET must be set; restart after changing them.
  • Login redirects but never lands in the app — over plain HTTP set SESSION_COOKIE_SECURE=false, and make sure CORS_ORIGINS includes http://localhost:5173.
  • atlas_schema_apply fails — confirm Postgres is up (docker compose ps) and DATABASE_URL is set.
  • Runner JWT rejected — re-check RUNNER_PRIVATE_KEY_FILE; if the key was rotated in the UI, download the new one and restart the group.