Skip to content
Galley

Docs / Start here

Quick start

Get a single-host Galley running with previews in about ten minutes.

Single host, single agent. Server, message bus, Postgres, ingress proxy, and one colocated agent all run on one machine. Good for evaluation, small teams, and the developer environment of someone who’ll later split things across hosts.

Prerequisites

  • Linux host with Docker 24+ and docker compose v2.
  • Public IP or a tunnel.
  • A wildcard DNS record (*.preview.yourco.dev) pointing at the host. The bare host (preview.yourco.dev) and any sub-subdomains both need to resolve.
  • 80/443 reachable from the internet (or wherever your reviewers sit).

1. Generate a master key

openssl rand -hex 32

Save the output. This key encrypts every secret in the database (project env vars, webhook secrets, OAuth tokens, the bypass tokens). It never goes into the database, and it’s not recoverable. Lose it and the ciphertext is rubble. Put it in a password manager or a Vault, and back it up somewhere separate from your Postgres backups.

2. Pull the compose file

mkdir -p /opt/galley && cd /opt/galley
curl -fsSL https://galley.sh/install/docker-compose.yml -o docker-compose.yml

The compose file pulls these images and wires them together:

  • galleysh/server:v1 — control plane
  • galleysh/agent:v1 — single colocated agent
  • postgres:16-alpine
  • nats:2.10-alpine
  • traefik:v3.6

There’s no build context — everything is a published image.

3. Configure environment

cat > .env <<'EOF'
GALLEY_MASTER_KEY=<the hex string from step 1>
GALLEY_PREVIEW_DOMAIN=preview.yourco.dev
GALLEY_PUBLIC_URL=https://galley.yourco.dev
GALLEY_LE_EMAIL=ops@yourco.dev
GALLEY_LE_DNS_PROVIDER=cloudflare
CLOUDFLARE_DNS_API_TOKEN=<your DNS provider token>
EOF
chmod 600 .env

Pick the DNS provider that hosts your zone — Galley uses the DNS-01 ACME challenge so wildcards work without exposing any service publicly during issuance. The provider variable names (CLOUDFLARE_DNS_API_TOKEN, ROUTE53_*, etc.) are listed on the DNS and TLS page.

4. Bring it up

docker compose up -d
docker compose logs -f galley-server

The server runs migrations on first boot, brings the agent online, and listens on https://galley.yourco.dev. First startup takes about 30 seconds; you’ll see server listening and agent online in the logs when it’s ready.

5. Bootstrap an admin account

The first user becomes an instance admin. Open the public URL and sign up — there’s no email verification on first install, so the first email + password through the form is the owner.

If you want to script this, the same is exposed as POST /api/v1/auth/setup — see Operations for the request shape.

6. Connect GitHub

In the dashboard, Admin → Instance → GitHub App: paste the App ID, private key, webhook secret, and client credentials for the App you registered in your org. Once saved, New project lets you install the App on the org and pick a repo. See GitHub setup for the full registration flow.

7. Open a PR

That’s it. Open a pull request against the connected repo. Within a minute you’ll see:

  • A new environment in the dashboard, building.
  • Live build logs streaming.
  • A preview URL when the build finishes.
  • A sticky GitHub comment on the PR with the URL and TTL.

Close the PR and the environment tears down within the next few seconds.

Next steps