Appearance
Self-hosting MergeBrief
These pages cover running your own MergeBrief Instance: an api, a web tier and a worker over one Postgres database, started from the shipped compose file. Read them in the order below the first time; after that, each page stands on its own.
Prerequisites
- Docker Engine with Docker Compose v2.24.4 or newer. The shipped compose files load
.envwith the longenv_fileform, apathplusrequired: false, which needs 2.24.0, and moving a host port uses the!overridetag, which needs 2.24.4 (compose.md). Older Compose releases reject both. Rundocker compose versionto check. The image is built forlinux/amd64andlinux/arm64. - A GitHub App you register yourself. There is no shared hosted App. Its App id, private key, webhook secret and OAuth client id and secret go in
.env(github-app.md). - A model provider API key. The zero-config default reads
ANTHROPIC_API_KEY;openaiandopenrouterread their own keys (generators.md). The subscription-billed CLI providers (claude-code,codex,cursor) run only as a process on your own machine outside the image, and the compose worker refuses them at boot (generators.md). - A public HTTPS URL in production. GitHub delivers webhooks only to a publicly reachable URL (github-app.md). The sign-in cookies are
__Host-cookies, which a browser keeps overhttps://or onhttp://localhost, never over plainhttp://on another hostname. Nothing in the stack speaks TLS, so a reverse proxy in front terminates it (compose.md).
Sizing
- Generations decide the worker's size. Concurrent generations are
WORKER_COUNTtimes the sum ofWORKER_CONCURRENCYandWORKER_LARGE_CONCURRENCY, two by default. An API provider holds one response stream per slot (generators.md). - Postgres grows with briefs. Each revision of a pull request stores its brief body as text, plus its revision summary and delta beside it. In the test fixtures a four-chunk brief body is about 6 KB and a synthetic 300-chunk one about 84 KB. What prunes itself and what does not is in operations.md.
- Memory and CPU per service are not yet measured on a release image. Read your own with
docker compose stats --no-stream, once idle and once while a brief generates, and size the host from the peak.
Cloud deployment
- Hetzner and EC2 deployment guide: a pinned release image on a VM, with the database on the VM, private RDS, or external Neon/Supabase, plus HTTPS and validation.
- Provider notes: official sources and connection details behind that guide.
Reading order
- github-app.md: which permissions and events to give the App, how reviewer sign-in works, and who triggers a brief.
- compose.md: the services, the
.envvalues a first boot needs, an external database, and the hardening steps before real exposure. - generators.md: the provider and model, the daily generation cap, the
operatorslist, and what force pushes and rebases do to a brief. - security-model.md: who can sign in, what each user can see, the trust boundaries, and every outbound destination with its off switch.
- configuration.md: every variable and config key, its default, and what an empty or bad value does.
- operations.md: upgrades, migrations, backup and restore, retention, tokens at rest, rotating secrets, the audit log and uninstalling.
- observability.md: the log line, the
evtnames to alert on, health endpoints and tracing. - troubleshooting.md: a symptom, its cause and the fix, with the log line or status you will see.
Read these when a repository or a reviewer needs them:
- repo-config.md: what a repository's own
.mergebrief/files can change about its briefs. - trackers.md: where the primary ticket is read from, and what the worker fetches from links in a pull request description.
- attachments.md: the one push the App makes, for images in review comments.
- cli.md: connecting the
mergebriefCLI, and the/api/*exemption an identity-aware proxy needs.