Docker Compose Deployment
Deploy Watchlight Beacon on any Linux or macOS host using Docker Compose. This is the fastest path from zero to a running control plane.
Prerequisites
| Requirement | Details |
|---|---|
| Docker Engine 24+ | Install Docker |
| Docker Compose v2 | Included with Docker Desktop; or install separately |
| 2 GB RAM minimum | 4 GB recommended for Tier 2, 8 GB for Tier 3 |
| GHCR access token | GitHub PAT with read:packages scope (provided by Watchlight AI) |
| curl, openssl | Required by the installer script |
Quick Start with the Beacon Installer
The self-contained installer (install-beacon.sh) is the recommended way to deploy Beacon with Docker Compose. It embeds all configuration files, manages secrets via OpenBao, and handles TLS setup automatically.
Download and Install
# Download the installer
curl -fsSL https://docs.watchlight.ai/install-beacon.sh -o install-beacon.sh
chmod +x install-beacon.sh
# Run the installer (interactive prompts)
./install-beacon.sh --ghcr-token <your-ghcr-token>
The installer will:
- Validate prerequisites (Docker version, Compose, available ports)
- Pull container images from GHCR
- Generate secrets in memory and store them in OpenBao (never written to disk)
- Start PostgreSQL and OpenBao infrastructure
- Start all Beacon application services
- Register a discovery scanner
- Configure TLS via Caddy reverse proxy
- Verify all containers are healthy
Non-Interactive Mode
Set environment variables to skip interactive prompts:
export BEACON_DOMAIN=beacon.company.com
export VERSION=0.3.0-preview
export GHCR_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
./install-beacon.sh
Deployment Profiles
The installer supports three profiles to match your deployment scenario.
| Profile | Use Case | TLS | Database | Secret Provider |
|---|---|---|---|---|
eval (default) | Evaluation and development | Caddy auto-TLS (self-signed or Let's Encrypt) | Embedded PostgreSQL | Embedded OpenBao |
production | Enterprise production | Service-level TLS (BYO certs) | External database (BYO) | AWS Secrets Manager, Azure Key Vault, or env |
production-caddy | Smaller production | Caddy auto-TLS | External database (BYO) | AWS Secrets Manager, Azure Key Vault, or env |
Caddy and OpenBao are optional infrastructure components included for convenience in evaluation. Production deployments (production profile) do not require either — you bring your own TLS certificates and secret provider (AWS Secrets Manager, Azure Key Vault, or environment variables).
Evaluation Profile
./install-beacon.sh --profile eval --ghcr-token <token>
Deploys all services with embedded infrastructure (PostgreSQL, OpenBao, Caddy). Uses self-signed TLS by default. Set a real domain for automatic Let's Encrypt certificates:
./install-beacon.sh --profile eval --domain beacon.company.com --ghcr-token <token>
Production Profile
./install-beacon.sh --profile production \
--tls-cert /path/to/cert.pem \
--tls-key /path/to/key.pem \
--ghcr-token <token>
Uses your own TLS certificates and external database. No Caddy proxy -- services handle TLS directly.
Production with Caddy
./install-beacon.sh --profile production-caddy \
--domain beacon.company.com \
--ghcr-token <token>
Caddy handles TLS termination, but uses an external database rather than the embedded PostgreSQL.
Tier-Based Deployment
The installer deploys Tier 1 services by default. Higher tiers will be configurable as Tier 2 and Tier 3 images become available in the installer.
| Tier | Services Deployed |
|---|---|
| Tier 1 | wl-registry, wl-registry-frontend, wl-discover, postgresql, openbao, caddy |
| Tier 2 | Tier 1 + wl-apdp, wl-apdp-frontend |
| Tier 3 | Tier 2 + wl-proxy, wl-secrets-broker |
Installer CLI Reference
Install Flags
| Flag | Default | Description |
|---|---|---|
--ghcr-token TOKEN | (prompt) | GHCR access token for image pulls |
--profile PROFILE | eval | Deployment profile: eval, production, production-caddy |
--domain DOMAIN | system hostname | Domain name for TLS certificates |
--version TAG | 0.3.0-preview | Container image version tag |
--license-key KEY | (none) | Watchlight license key (JWT) |
--log-level LEVEL | info | Log level: debug, info, warn, error |
--registry-port PORT | 8443 | HTTPS port for the registry dashboard |
--install-dir PATH | /opt/watchlight-beacon | Installation directory |
--agent-reg-mode MODE | open | Agent registration: open, token_required, disabled |
--tls-cert PATH | (none) | TLS certificate (production profile) |
--tls-key PATH | (none) | TLS private key (production profile) |
Operations
| Flag | Description |
|---|---|
--status | Show container states, health, and access URLs |
--upgrade | Pull new images and restart services (preserves data) |
--uninstall | Stop all containers and remove volumes and install directory |
Environment Variables
Key environment variables used by Beacon services:
| Variable | Service | Description |
|---|---|---|
DATABASE_URL | wl-registry | PostgreSQL connection string |
HOST | wl-registry | Bind address (default 0.0.0.0) |
PORT | wl-registry | Listen port (default 8080) |
LOG_LEVEL | all services | Log verbosity |
REGISTRY_URL | wl-discover | URL of the wl-registry API |
AGENT_ID | wl-discover | Scanner agent identity |
AGENT_REGISTRATION_MODE | wl-registry | open, token_required, disabled |
WL_LICENSE_KEY | all services | License key for production use |
TLS Architecture
All external traffic is encrypted by default:
- Caddy profiles: Caddy terminates TLS and reverse-proxies to backend services
- Production profile: Each service handles TLS directly using provided certificates
- Internal traffic: OpenBao and PostgreSQL use self-signed TLS on an isolated Docker network
- Self-signed mode: Set domain to
localhost; Caddy generates self-signed certs and exports a CA cert to./beacon-ca.crt - Let's Encrypt: Set a public domain and ensure ports 443/80 are accessible
Common Operations
# View all service logs
docker compose -f docker-compose.yml logs -f
# View logs for a specific service
docker compose -f docker-compose.yml logs -f wl-registry
# Stop services (preserves data)
docker compose -f docker-compose.yml down
# Restart after reboot
docker compose -f docker-compose.yml up -d
# Check status via the installer
./install-beacon.sh --status
# Upgrade to a new version
./install-beacon.sh --upgrade --version 0.4.0 --ghcr-token <token>
# Full reset (destroys all data)
./install-beacon.sh --uninstall
Troubleshooting
| Issue | Solution |
|---|---|
docker login returns unauthorized | Verify your GHCR token has read:packages scope |
| Port conflict on 8443 | Use --registry-port to change the default |
| Browser certificate warning | Trust the CA cert exported to ./beacon-ca.crt, or use curl -k |
| Services fail to start | Check logs: docker compose -f docker-compose.yml logs |
| wl-discover not finding containers | Ensure target containers are on the beacon-partner Docker network |
| Database connection errors | Check PostgreSQL health: docker inspect beacon-postgres --format='{{.State.Health.Status}}' |
| License expired | Contact sales@watchlight.ai for renewal |
Next Steps
- Deploy to Kubernetes with the Helm guide