Manual Install

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

Create a Docker network

All MergeWatch containers must communicate over a shared network.

docker network create mergewatch-net

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.

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/mergewatch/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:

Bedrock

-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 \

LiteLLM

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

Ollama

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

(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/mergewatch/mergewatch-dashboard:latest

The dashboard reads directly from the MergeWatch Postgres database, so no NEXT_PUBLIC_API_URL is required.

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

Install the GitHub App

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

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

Task	Command
View logs	`docker logs -f mergewatch`
Restart server	`docker restart mergewatch`
Stop all	`docker stop mergewatch dashboard postgres`
Remove all	`docker rm mergewatch dashboard postgres`
Pull latest images	`docker pull ghcr.io/mergewatch/mergewatch:latest && docker pull ghcr.io/mergewatch/mergewatch-dashboard:latest`

To upgrade, pull the latest images and recreate the containers:

docker pull ghcr.io/mergewatch/mergewatch:latest
docker stop mergewatch && docker rm mergewatch
# Re-run the docker run command from Step 3

Overview

Self-Hosting

LLM Providers

Platform Guides

Configuration

GitHub App

Deployment

Dashboard

Managed SaaS

Reference

When to use manual install

Prerequisites

Deployment steps

Managing containers

Next steps

Docker Compose Install

Environment Variables

​When to use manual install

​Prerequisites

​Deployment steps

​Managing containers

​Next steps

Docker Compose Install

Environment Variables

When to use manual install

Prerequisites

Deployment steps

Managing containers

Next steps