Skip to main content

Docker Control Plane

Wavry distributes control-plane services as containers only.

Services:

  • gateway: auth and control APIs
  • relay: encrypted UDP relay fallback

Raw release binaries for these services are intentionally not published.

Quick Start​

Start gateway:

docker compose -f docker/control-plane.compose.yml up -d gateway

Optional relay:

WAVRY_RELAY_MASTER_URL=http://host.docker.internal:8080 \
docker compose -f docker/control-plane.compose.yml --profile relay up -d relay

Check status:

docker compose -f docker/control-plane.compose.yml ps

Images and Tags​

Images:

  • ghcr.io/<owner>/<repo>/gateway
  • ghcr.io/<owner>/<repo>/relay

Tag policy:

  • production: pin explicit release tag (vX.Y.Z, vX.Y.Z-canary..., or vX.Y.Z-unstable...)
  • development: main or latest

Environment Variables​

Key values in docker/control-plane.compose.yml:

VariablePurposeDefault
WAVRY_CONTROL_PLANE_TAGimage taglatest
WAVRY_IMAGE_REPOimage repo baseghcr.io/bybrooklyn/wavry
WAVRY_GATEWAY_PORTpublished gateway port0 (auto-allocate)
ADMIN_PANEL_TOKENadmin API access tokenempty
WAVRY_RELAY_PORTpublished relay UDP port0 (auto-allocate)
WAVRY_RELAY_HEALTH_PORTpublished relay health HTTP port0 (auto-allocate)
WAVRY_RELAY_MASTER_URLrelay upstream registration targethttp://host.docker.internal:8080
WAVRY_RELAY_MASTER_PUBLIC_KEYrelay signature verification keyempty
WAVRY_RELAY_ALLOW_INSECURE_DEVinsecure relay mode (dev only)1

Auto-allocation avoids local port collisions with other services. To pin ports, set explicit values.

Production Baseline​

Before production rollout:

  1. Set WAVRY_RELAY_MASTER_PUBLIC_KEY.
  2. Set WAVRY_RELAY_ALLOW_INSECURE_DEV=0.
  3. Set ADMIN_PANEL_TOKEN to a high-entropy token.
  4. Pin image tags (do not use floating tags).
  5. Put gateway behind TLS termination + ingress controls.
  6. Keep relay health endpoint private (do not expose publicly unless required).

Volumes and Persistence​

Default volumes:

  • gateway: /var/lib/wavry
  • relay: /var/lib/wavry-relay

Recommendation:

  • back up gateway persistent state regularly
  • treat relay state as less critical but keep for diagnostics continuity

Upgrade and Rollback​

Upgrade​

  1. Update WAVRY_CONTROL_PLANE_TAG.
  2. Pull images:
docker compose -f docker/control-plane.compose.yml pull
  1. Deploy updated containers:
docker compose -f docker/control-plane.compose.yml up -d
  1. Resolve published ports and validate:
docker compose -f docker/control-plane.compose.yml port gateway 3000
docker compose -f docker/control-plane.compose.yml port relay 9091

Rollback​

  1. Restore previous known-good tag.
  2. Re-run docker compose ... up -d.
  3. Validate health and session creation path.

Logs and Diagnostics​

Tail logs:

docker compose -f docker/control-plane.compose.yml logs -f gateway
docker compose -f docker/control-plane.compose.yml logs -f relay

If relay registration fails:

  • verify WAVRY_RELAY_MASTER_URL
  • verify reachability to upstream master
  • verify master public key configuration for secure mode

Security Notes​

  • relay should not decrypt media payloads
  • never place secrets directly in source-controlled compose files
  • use environment injection or secret-management tooling