Docker Compose Deployment

Get DocuGardener running locally in under 10 minutes with Docker Compose.

Before you start: Make sure you have met all prerequisites, including Docker 24+, Node.js 20+, and an LLM API key (or Ollama installed).

Clone the repository

git clone https://github.com/docugardener/docugardener.git
cd docugardener

Configure environment variables

cp .env.example .env
cp web/.env.example web/.env

Open both files in your editor and fill in the required values. At minimum you need: GITHUB_APP_ID, GITHUB_WEBHOOK_SECRET, LLM_PROVIDER plus the corresponding API key, ENCRYPTION_KEY (generate with openssl rand -hex 32), and NEXTAUTH_SECRET (generate with openssl rand -base64 32). See the full environment variable reference for details.

DEPLOYMENT_MODE: The correct value for all self-hosted installs is saas. Do not change this to air-gap — that mode is for fully offline enterprise environments with no GitHub connectivity. If you copy values from an existing instance, double-check this setting.

GitHub App params (GITHUB_APP_ID, GITHUB_WEBHOOK_SECRET, GITHUB_PRIVATE_KEY_PATH) go in root .env only — the web frontend reads them via the backend API. Do not add them to web/.env.

Add the GitHub App private key

mkdir -p secrets
chmod 600 secrets/github-app.pem

Place the PEM file downloaded from your GitHub App settings at secrets/github-app.pem, then lock down its permissions with the command above.

Install web dependencies

cd web && npm install && cd ..

Installs Node.js dependencies. This must run before make dev-up — the Makefile runs Prisma migrations via npx prisma migrate deploy which requires node_modules to be present.

Start infrastructure services

make dev-up

This starts PostgreSQL, Redis, Weaviate, the FastAPI analysis server, and the RQ worker, and runs Prisma migrations automatically. First run may take a few minutes to pull images.

macOS (Colima): set DOCKER_HOST before running: export DOCKER_HOST="unix://$HOME/.colima/default/docker.sock"

Start the web server

For development (recommended):

make web-dev

Or directly:

cd web && npm run dev

For production:

cd web && npm run build && npm start

Verify the analysis plane

curl http://localhost:8000/health

You should see: {"status":"healthy"}

Open DocuGardener

Navigate to http://localhost:3000 in your browser and complete the onboarding wizard.

⚠️ GitHub App isolation: never install your local dev GitHub App and a production GitHub App on the same repository simultaneously. Each installation fires its own webhook independently — both will analyse the same PR and each will open a separate fix PR, resulting in duplicates. Use a dedicated dev-only test repository (e.g. my-org/sandbox-dev) and keep the production app installed only on repositories that should receive production analysis.

Service Map

Service	Port	Purpose
Next.js (web)	3000	Dashboard, auth, settings, billing
FastAPI (api)	8000	Webhook handler, analysis API, health checks
PostgreSQL	5433	Primary database for both planes
Redis	6379	Job queue (RQ) and caching
Weaviate	8080	Vector database for document embeddings
Grafana	3004	Monitoring dashboards (optional)

Local Development: Webhook Proxy

GitHub cannot send webhooks to localhost. For local development, use smee.io as a webhook proxy:

# Install the smee client
npm install -g smee-client

# Create a channel at https://smee.io/new, then run:
smee --url https://smee.io/YOUR_CHANNEL --target http://localhost:8000/api/webhooks/github

Set your GitHub App’s webhook URL to the smee.io channel URL. In production, point it directly at your server’s /api/webhooks/github endpoint.

Troubleshooting

Stale containers from a previous installation

If you’re reinstalling on the same machine, container name conflicts from a previous instance will cause make dev-up to fail. Remove the old containers first:

docker rm -f docugardener docugardener-worker docugardener-smee \
             docugardener-weaviate docugardener-postgres docugardener-redis

Inbox is empty after first PR

If jobs appear in the Jobs list but the Inbox stays empty, the most common cause is DEPLOYMENT_MODE=air-gap in your .env. This creates a default tenant at startup that intercepts webhooks before your real tenant is set up. Set DEPLOYMENT_MODE=saas in both .env and web/.env, restart all containers, and re-open the PR.

Container fails to start

Check logs with docker compose --env-file .env -f docker/docker-compose.yml logs -f. Common issues: port conflicts (another service on 5433 or 6379), missing .env file, or insufficient disk space for Weaviate.

Health check returns unhealthy

Ensure the database is reachable and migrations have been applied. Check that DATABASE_URL in your .env matches the PostgreSQL container’s credentials.

Webhooks not arriving

Verify the smee proxy is running and the channel URL matches what you configured in your GitHub App settings. Check the “Recent Deliveries” tab in your GitHub App to see if GitHub is sending the webhooks successfully.