Self-hosting

Quickstart

A minimal self-host boot path for maintainers: start the service, verify readiness, and keep the first rollout safe.

1. Copy the sample env

The sample env contains placeholders only. Keep your real .env out of git and prefer mounted secret files for multiline values like the GitHub App private key.

cp .env.example .env
# edit .env

bash

2. Start conservative

Begin with a small allowlist, unified comments, safety, and grounding. Leave AI, RAG, and REES off until webhook delivery and deterministic review are working.

.env

SELFHOST_DEPLOYMENT_MODE=dry-run
GITTENSORY_REVIEW_REPOS=owner/repo
GITTENSORY_REVIEW_UNIFIED_COMMENT=true
GITTENSORY_REVIEW_SAFETY=true
GITTENSORY_REVIEW_GROUNDING=true
GITTENSORY_REVIEW_RAG=false
GITTENSORY_REVIEW_ENRICHMENT=false

dry-run computes reviews but suppresses writes. Switch to live only after webhook delivery, logs, and review output match expectations.

3. Boot the stack

docker compose up -d --build
curl http://localhost:8787/health
curl http://localhost:8787/ready

bash

/health: Liveness. It confirms the HTTP process is up.
/ready: Readiness. It returns 200 only after database access and migrations are healthy.
/metrics: Prometheus metrics for queue, jobs, HTTP traffic, uptime, and AI usage.

4. Install or connect the GitHub App

Point your App webhook to https://your-host.example/v1/github/webhook, set the same webhook secret in GITHUB_WEBHOOK_SECRET, install the App on one test repo, and open a small PR. The direct App and Orb modes are covered in GitHub App and Orb.

5. Watch the first review

Look for these logs during boot and the first webhook:

selfhost_listening
selfhost_migrations_applied
selfhost_ai_provider          # only when AI_PROVIDER is set
selfhost_job_dead             # investigate immediately if present
review_context_fetch_failed   # REES/RAG/grounding context failure

After the deterministic path is stable, continue with Configuration and then layer in AI, REES, or RAG deliberately.

← PreviousOverview Next →Configuration