Docker Watcher

Automated Docker deployment orchestrator with a web dashboard. Watches container registries for new image tags and deploys them with zero-downtime blue-green strategy, health checks, and automatic NPM (Nginx Proxy Manager) proxy configuration.

Features

• Registry polling and webhook receiver for automatic deployments
• Blue-green deploys with health checks and automatic rollback
• NPM integration for automatic reverse proxy configuration
• Multi-stage projects (dev, staging, prod) with tag pattern matching
• Real-time deploy logs via SSE streaming
• OIDC/SSO support alongside local auth
• Encrypted credential storage (AES-256-GCM)
• Single binary with embedded SPA frontend

Prerequisites

• Docker with Docker Compose
• A Docker network for deployed containers (e.g. staging-net)
• Nginx Proxy Manager (optional, for automatic proxy configuration)
• Wildcard DNS pointing to your server (for subdomain-based routing)

Quick Start

1. Create the Docker network (containers will be attached to this):

   docker network create staging-net
   

2. Create a .env file (see .env.example):

   cp .env.example .env
   # Edit .env and set ENCRYPTION_KEY and ADMIN_PASSWORD
   # Generate a key: openssl rand -hex 32
   

3. Start Docker Watcher:

   docker compose up -d
   

4. Open the dashboard at http://localhost:8080 and log in with admin / your ADMIN_PASSWORD.

Configuration

Environment Variables

Variable	Required	Description
ENCRYPTION_KEY	Yes	AES-256 key for encrypting stored credentials. Use openssl rand -hex 32
ADMIN_PASSWORD	Yes (first launch)	Password for the default admin user
SEED_FILE	No	Path to YAML seed config (default: ./docker-watcher.yaml)
DATA_DIR	No	SQLite database directory (default: ./data)
LISTEN_ADDR	No	HTTP listen address (default: :8080)
NPM_URL	No	Override NPM API URL (otherwise uses value from settings)
POLLING_INTERVAL	No	Registry polling interval, Go duration string e.g. 5m (default from settings)

Seed Config

On first launch, Docker Watcher imports a YAML seed file to pre-configure registries, projects, and settings. See docker-watcher.example.yaml for the full format.

Webhook Integration

After setup, find your webhook URL at Settings > Webhook URL in the dashboard. Configure your CI/CD (Gitea Actions, GitHub Actions) to POST to this URL on image push:

curl -X POST https://your-domain/api/webhook/<secret> \
  -H "Content-Type: application/json" \
  -d '{"image": "registry.example.com/org/app:v1.2.3"}'

OIDC Setup

1. Go to Settings > Auth in the dashboard
2. Switch auth mode to OIDC
3. Enter your provider's Issuer URL, Client ID, and Client Secret
4. Set the Redirect URL to https://your-domain/api/auth/oidc/callback

Development

# Build frontend
cd web && npm install && npm run build && cd ..

# Run backend (requires ENCRYPTION_KEY and ADMIN_PASSWORD env vars)
go run ./cmd/server

# Or use Make
make build
make dev

Architecture

CI/Registry --> Webhook/Poller --> Deployer --> Docker + NPM
                                      |
                                  Event Bus --> SSE --> Web Dashboard

• Backend: Go 1.24, chi router, SQLite (pure Go), Docker SDK
• Frontend: SvelteKit 2, Tailwind CSS 4, TypeScript
• Deployment: Single binary with embedded SPA, multi-stage Dockerfile