Skip to content
Breeze RMM

Production Deployment

Breeze ships as pre-built Docker images on GitHub Container Registry. A single docker compose up -d brings up a fully working production stack with automatic TLS.

What Gets Deployed

The core stack (docker-compose.yml) includes:

ServiceImagePurpose
Binaries Initghcr.io/lanternops/breeze/binariesCopies agent/viewer binaries to a shared volume, then exits
Caddycaddy:2.8-alpineReverse proxy, auto-TLS, security headers
APIghcr.io/lanternops/breeze/apiHono API server
Webghcr.io/lanternops/breeze/webAstro SSR dashboard
PostgreSQLpostgres:16-alpinePrimary database
Redisredis:7-alpineJob queue, caching, rate limiting

An optional monitoring stack (Prometheus, Grafana, Alertmanager, Loki, Promtail, exporters) is available as a separate overlay — see Monitoring.

Deploy Steps

  1. Prepare the server

    You need Docker and Docker Compose on a Linux VPS. See Prerequisites.

  2. Clone and configure

    Terminal window
    git clone https://github.com/LanternOps/breeze.git
    cd breeze
    cp .env.example .env

  3. Set your domain and secrets

    Edit .env and set these required values:

    Terminal window
    BREEZE_DOMAIN=breeze.yourdomain.com
    ACME_EMAIL=admin@yourdomain.com

    Generate all secrets at once:

    Terminal window
    for key in JWT_SECRET APP_ENCRYPTION_KEY MFA_ENCRYPTION_KEY \
      ENROLLMENT_KEY_PEPPER MFA_RECOVERY_CODE_PEPPER \
      METRICS_SCRAPE_TOKEN SESSION_SECRET TURN_SECRET; do
      echo "${key}=$(openssl rand -hex 32)"
    done
    

    echo "AGENT_ENROLLMENT_SECRET=$(openssl rand -hex 32)"
    echo "POSTGRES_PASSWORD=$(openssl rand -base64 24 | tr -d '/+=')"

    Paste the output into .env.

  4. Start the stack

    Terminal window
    docker compose up -d

    That’s it. On first start, the API container automatically runs database migrations and seeds the initial admin user. Caddy obtains a TLS certificate from Let’s Encrypt.

  5. Verify the deployment

    Terminal window
    # Check health
    curl https://breeze.yourdomain.com/health
    

    # Check running containers
    docker compose ps
    

    # View API logs
    docker compose logs -f api

Adding Monitoring

The monitoring stack lives in a separate compose overlay file (docker-compose.monitoring.yml) and includes Prometheus, Grafana, Alertmanager, Loki, Promtail, and database exporters.

To deploy with monitoring:

Terminal window
docker compose -f docker-compose.yml -f docker-compose.monitoring.yml up -d

Add a Grafana password to .env:

Terminal window
GRAFANA_ADMIN_PASSWORD=$(openssl rand -base64 16 | tr -d '/+=')

Grafana is available at http://127.0.0.1:3000 (localhost only by default).

Pinning a Version

By default, images pull the latest tag. To pin to a specific release:

Terminal window
# In .env
BREEZE_VERSION=0.3.0

Then pull and restart:

Terminal window
docker compose pull && docker compose up -d

Resource Tuning

Override default resource limits via environment variables:

Terminal window
# Redis memory limit (default: 256mb)
REDIS_MAXMEMORY=512mb

Updating

Terminal window
cd breeze
git pull origin main
docker compose pull
docker compose up -d

Pre-built images are pulled from GHCR. Database migrations run automatically on startup.