Skip to main content

​
When to use manual install

Use this guide if you:
  • Cannot use Docker Compose (minimal Docker installations, orchestration platforms that run individual containers)
  • Want individual control over each container’s lifecycle
  • Need to integrate MergeWatch containers into an existing infrastructure setup
For most users, the recommended path is Docker Compose. See the install guide for the simpler setup.

​
Prerequisites

  • Docker installed and running
  • A GitHub App configured with the required permissions
  • Your GitHub App credentials: App ID, private key (.pem file), and webhook secret
  • An API key or endpoint for your chosen LLM provider

​
Deployment steps

1

Create a Docker network

All MergeWatch containers must communicate over a shared network.
docker network create mergewatch-net
2

Start Postgres

MergeWatch requires a Postgres database for storing installation and review data.
docker run -d \
  --name postgres \
  --network mergewatch-net \
  -e POSTGRES_USER=mergewatch \
  -e POSTGRES_PASSWORD=mergewatch \
  -e POSTGRES_DB=mergewatch \
  -v mergewatch-pgdata:/var/lib/postgresql/data \
  -p 5432:5432 \
  postgres:16-alpine
The -v mergewatch-pgdata:/var/lib/postgresql/data flag creates a named volume so your data persists across container restarts.
3

Start the MergeWatch server

Run the MergeWatch server container, passing all required environment variables via -e flags.
docker run -d \
  --name mergewatch \
  --network mergewatch-net \
  -e GITHUB_APP_ID=your_app_id \
  -e GITHUB_PRIVATE_KEY="$(cat private-key.pem)" \
  -e GITHUB_WEBHOOK_SECRET=your_webhook_secret \
  -e DATABASE_URL=postgresql://mergewatch:mergewatch@postgres:5432/mergewatch \
  -e LLM_PROVIDER=anthropic \
  -e ANTHROPIC_API_KEY=sk-ant-your-key \
  -p 3000:3000 \
  ghcr.io/santthosh/mergewatch:latest
Replace the placeholder values with your actual credentials. The DATABASE_URL hostname postgres matches the --name of the Postgres container on the shared network.
For other LLM providers, replace the provider-specific variables:
-e LLM_PROVIDER=bedrock \
-e AWS_REGION=us-east-1 \
-e AWS_ACCESS_KEY_ID=your_access_key \
-e AWS_SECRET_ACCESS_KEY=your_secret_key \

-e LLM_PROVIDER=litellm \
-e LITELLM_BASE_URL=http://litellm:4000 \
-e LITELLM_API_KEY=your_litellm_key \

-e LLM_PROVIDER=ollama \
-e OLLAMA_BASE_URL=http://ollama:11434 \
4

(Optional) Start the dashboard

docker run -d \
  --name dashboard \
  --network mergewatch-net \
  -e DEPLOYMENT_MODE=self-hosted \
  -e DATABASE_URL=postgres://postgres:postgres@postgres:5432/mergewatch \
  -e GITHUB_CLIENT_ID=your_client_id \
  -e GITHUB_CLIENT_SECRET=your_client_secret \
  -e NEXTAUTH_SECRET=$(openssl rand -base64 32) \
  -e NEXTAUTH_URL=http://localhost:3001 \
  -p 3001:3001 \
  ghcr.io/santthosh/mergewatch-dashboard:0.1.0
The dashboard reads directly from the MergeWatch Postgres database, so no NEXT_PUBLIC_API_URL is required.
5

Update the GitHub App webhook URL

Go to your GitHub App settings and set the Webhook URL to your server’s publicly accessible URL (e.g. https://mergewatch.example.com/webhook).For local development, use a tunnel:
ngrok http 3000
6

Install the GitHub App

Navigate to your GitHub App’s public page and install it on the repositories you want MergeWatch to review.
7

Verify the deployment

Check that all containers are running:
docker ps --filter network=mergewatch-net
Check the MergeWatch server logs:
docker logs mergewatch

​
Managing containers

TaskCommand
View logsdocker logs -f mergewatch
Restart serverdocker restart mergewatch
Stop alldocker stop mergewatch dashboard postgres
Remove alldocker rm mergewatch dashboard postgres
Pull latest imagesdocker pull ghcr.io/santthosh/mergewatch:latest && docker pull ghcr.io/santthosh/mergewatch-dashboard:latest
To upgrade, pull the latest images and recreate the containers: 
docker pull ghcr.io/santthosh/mergewatch:latest
docker stop mergewatch && docker rm mergewatch
# Re-run the docker run command from Step 3

​
Next steps

Docker Compose Install

Use Docker Compose for a simpler setup experience.

Environment Variables

Full reference for all environment variables.