Self-Hosted Deployment

Deploy MergeWhy on your own infrastructure with Docker Compose or Kubernetes.

Overview

MergeWhy can be deployed on your own infrastructure for organizations that require data sovereignty, air-gapped environments, or custom compliance requirements. The self-hosted edition supports Docker Compose for small teams and Kubernetes (Helm) for production deployments.

Docker Compose

The fastest way to run MergeWhy self-hosted. Requires Docker and Docker Compose v2.

docker-compose.yml (minimal)

# Clone the repository
git clone https://github.com/mergewhy/mergewhy.git
cd mergewhy

# Copy environment template
cp .env.example .env.local

# Edit .env.local with your configuration
# Required: OIDC_ISSUER_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET

# Start core services (PostgreSQL + App)
docker compose up -d

# With S3-compatible storage (MinIO)
docker compose --profile s3 up -d

# With local LLM (Ollama)
docker compose --profile llm up -d

# Full stack
docker compose --profile s3 --profile llm up -d

Note

The Docker Compose stack includes PostgreSQL 16, automatic database migrations, and a health-checked application container. Data is persisted in Docker volumes.

Kubernetes (Helm)

For production deployments, use the included Helm chart. It supports horizontal scaling, external PostgreSQL, and ingress configuration.

Helm installation

# Add the MergeWhy Helm repository
helm repo add mergewhy https://charts.mergewhy.com

# Install with custom values
helm install mergewhy mergewhy/mergewhy \
  --namespace mergewhy \
  --create-namespace \
  -f values.yaml

# Or install from the local chart
helm install mergewhy ./deploy/helm/mergewhy \
  --namespace mergewhy \
  --create-namespace \
  -f values.yaml

Helm Values

values.yaml (example)

replicaCount: 2

image:
  repository: ghcr.io/mergewhy/mergewhy
  tag: latest

env:
  DEPLOYMENT_MODE: "self-hosted"
  AUTH_PROVIDER: "oidc"
  OIDC_ISSUER_URL: "https://your-idp.example.com"
  OIDC_CLIENT_ID: "mergewhy"
  STORAGE_PROVIDER: "s3"
  S3_BUCKET: "mergewhy-evidence"
  S3_REGION: "us-east-1"

postgresql:
  enabled: false  # Use external database
  externalHost: "your-rds-instance.us-east-1.rds.amazonaws.com"

ingress:
  enabled: true
  className: "nginx"
  hosts:
    - host: mergewhy.internal.company.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: mergewhy-tls
      hosts:
        - mergewhy.internal.company.com

Architecture

The self-hosted deployment uses a pluggable provider architecture. Four environment variables control the entire stack:

DEPLOYMENT_MODE — “saas” or “self-hosted”
AUTH_PROVIDER — “clerk” (SaaS) or “oidc” (self-hosted)
STORAGE_PROVIDER — “database” or “s3”
LLM_PROVIDER — “anthropic”, “openai”, “ollama”, or “none”

Warning

All providers use lazy singletons with dynamic imports. Clerk is never bundled in OIDC mode, and next-auth is never bundled in SaaS mode.

Getting Started Configuration