Install with Docker Compose

The Compose bundle runs MergeHarbor on one Linux VM, for small teams, on-premises servers and evaluations. It includes PostgreSQL with pgvector, an embeddings server and Caddy for TLS, so nothing else is needed. For larger installations, use Helm.

Requirements

• Linux with Docker Engine 24 or later and the Docker Compose plugin 2.24 or later
• openssl
• At least 4 vCPU, 8 GB RAM and 50 GB free disk (see Sizing)
• Ports 80 and 443 free, and a DNS name for the VM
• linux/amd64 or linux/arm64

./install.sh --check checks all of this without changing anything.

Install

Get the bundle (the deploy/self-hosted directory of a release, or the self-hosted/ directory of the air-gap bundle). Then:

./install.sh --domain mergeharbor.example.com --version 1.4.0 --admin-email you@example.com
$EDITOR .env                                  # review model, code host, email
./compose.sh up -d
./create-admin.sh --org-name "Example Corp"
cp /path/to/mergeharbor.lic license/mergeharbor.lic

What each step does:

1. install.sh
   • Checks prerequisites and creates .env from .env.example.
   • Generates every secret locally with openssl into secrets.env (mode 600). Secrets are never printed, and an existing value is never replaced.
   • Pulls the images, starts everything and waits until the API is healthy.
2. Edit .env to choose the review model and connect your code host. Run ./compose.sh up -d to apply changes. Always use ./compose.sh rather than docker compose: it loads both .env and secrets.env.
3. create-admin.sh
   • Creates the first organization and prints a one-time link for its owner, who becomes an instance administrator.
   • Uses the break-glass admin token from inside the API container, then turns the token off again.
   • Works without email.
4. Copy the license file. Until a valid license is in place, reviews are paused. It is re-read every minute, so no restart is needed.

Configuration

Setting in .env	Purpose
MERGEHARBOR_DOMAIN, MERGEHARBOR_VERSION, MERGEHARBOR_REGISTRY	Host name, release (X.Y.Z), and image registry (default ghcr.io/mergeharbor)
TLS_MODE	auto (Let’s Encrypt; needs a public name), internal (Caddy’s own certificate authority) or files (certs/tls.crt and certs/tls.key)
LLM_BACKEND, ANTHROPIC_API_KEY	The Anthropic API
LLM_BACKEND=bedrock, AWS_REGION, AWS credentials	Amazon Bedrock
SELFHOSTED_LLM_BASE_URL	Your own OpenAI-compatible model server; register and price the model in config/models.yaml
MODEL_PROVIDERS	The providers configured above, for example anthropic or openai_compatible. Routing never uses another.
GITHUB_APP_* and other code host settings	See GitHub, GitLab and the other code host guides
SMTP_*	Email for invitations and notifications
RESOURCE_PROFILE	small, medium or large (with matching memory limits)
CA_BUNDLE	Extra certificate authorities, for code hosts or model servers with a private CA
AIR_GAPPED	true limits every outbound call to private networks

Operations

Task	Command
Status and logs	./compose.sh ps, ./compose.sh logs -f api worker
Back up the database and configuration	./backup.sh. Schedule it, and copy backups/ off the VM.
Restore	./backup.sh restore backups/<file>.dump
Upgrade	./upgrade.sh 1.5.0; see Upgrades

Proof runs (the optional sandbox that runs generated tests) are not part of the Compose bundle. They need their own isolated host; use the Helm chart for them.