Overview

Galley turns every pull request into a running copy of your application — a unique URL, a fresh database, real services. When the PR closes, the preview is removed.

It’s distributed as Docker images. One compose file installs every piece on one host: the server, the message bus, Postgres, the ingress proxy, and a colocated agent. There is no source distribution to build, no separate binaries to download.

A multi-host topology — control plane on a small box, agents on a fleet — is on the roadmap. v1 is single-host: install on one machine, run as many previews as that machine fits.

Components

Component	What it does	Where it runs
galley-server	HTTP API, webhook endpoint, dashboard, audit log	Control plane
Postgres	Stores projects, environments, deployments, encrypted secrets	Control plane
Message bus	Build job dispatch, agent heartbeats, live event/log streams	Control plane
Ingress proxy	Public ingress, wildcard subdomain routing, TLS	Control plane (or wherever previews resolve to)
galley-agent	Builds images, runs preview containers, captures logs + screenshots	Each docker host

The server is the single place that talks to your database. The agent talks to the message bus, the local Docker daemon, and (for git ops + image pulls) the public internet. Agents never reach Postgres directly.

Lifecycle

1. Webhook arrives. GitHub fires pull_request.opened. The server verifies the HMAC, finds the project, creates an environment, queues a build job.
2. Agent claims the job. It clones the repo, parses galley.yml, and per service either uses your Dockerfile or falls back to language autodetect.
3. Builds run in parallel up to a concurrency cap. Per-service log lines stream live to the dashboard.
4. Containers come up in dependency order, each on the env’s private network with a DNS alias matching its galley.yml name. Web/api services get a public route at <service>.pr-<n>-<repo>.preview.yourco.dev (or the bare env domain when there’s a single web service).
5. Health checks pass, screenshots fire for kind: web services, the PR comment updates with the URL.
6. PR closes → server signals teardown, the agent removes containers + networks, the deployment is marked superseded.

What you need before installing

• A Linux host with Docker. 2 vCPU + 4 GB RAM is enough to start; more if you’ll run many concurrent previews.
• A wildcard DNS record — *.preview.yourco.dev — pointed at the host.
• A 32-byte master key. Generate one with openssl rand -hex 32 and keep it somewhere you back up separately from the database (a password manager, a Vault, the secret manager you already use).
• A GitHub App registered for your org (or, for solo accounts, a Personal Access Token).

The next page walks through the single-host path end to end in roughly ten minutes.