Production Setup Reference

This document serves as the authoritative production reference for running CollectorCtrl at enterprise scale: firewall rules, host prerequisites, server address advertisement, offline package mirroring, and PostgreSQL database setup.

1. Network & Firewall Port Requirements

Ensure host security groups, Kubernetes ingress rules, and corporate firewalls permit traffic on the following required ports:

2. Target Host Prerequisites

Before deploying the Supervisor agent on target Linux or Windows hosts, verify:

3. Server Address Advertisement

Agents resolve the Management Server address automatically via the /api/onboard/serverinfo endpoint. The server determines its advertise address in the following priority order:

4. Offline & Air-Gapped Fleets (Package Mirror)

For corporate environments without outbound internet access on worker nodes, CollectorCtrl includes built-in package mirroring:

• Automatic Mirroring: The server mirrors supervisor release binaries from GitHub on startup and syncs every 6 hours into /packages/.
• Zero-Internet Onboarding: Onboarding scripts query http://YOUR_SERVER:4321/packages/ first before falling back to external mirrors.

Environment Variable Overrides

5. Production Database: PostgreSQL Setup

While SQLite is configured by default for evaluation, enterprise deployments handling large fleets should use a high-concurrency PostgreSQL 14+ database.

Docker Compose Production Template

version: '3.8'

services:
collectorctrl-server:
  image: ghcr.io/collectorctrl/collectorctrl-server:latest
  ports:
    - "4320:4320" # OpAMP WebSocket
    - "4321:4321" # Web Dashboard UI & REST API
  environment:
    - COLLECTORCTRL_MODE=production
    - COLLECTORCTRL_DB_TYPE=postgres
    - COLLECTORCTRL_DB_DSN=host=postgres user=postgres password=postgres dbname=collectorctrl port=5432 sslmode=disable
    - COLLECTORCTRL_JWT_SECRET=change_this_secret_in_production
  depends_on:
    postgres:
      condition: service_healthy

postgres:
  image: postgres:15-alpine
  environment:
    - POSTGRES_USER=postgres
    - POSTGRES_PASSWORD=postgres
    - POSTGRES_DB=collectorctrl
  ports:
    - "5432:5432"
  volumes:
    - postgres_data:/var/lib/postgresql/data
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U postgres"]
    interval: 5s
    timeout: 5s
    retries: 5

volumes:
postgres_data:

6. Dynamic Configuration Reconciliation Flow

When an administrator updates policy rules in the UI, the Supervisor executes a supervised configuration lifecycle:

7. Logs & Troubleshooting Reference