Setup & Installation Guide

This guide details the prerequisites, deployment procedures, service configuration, and troubleshooting steps required to install and run the CollectorCtrl Management Server and the Supervisor Agent in production environments.

Network & Firewalls: Port Allocation

Ensure your network security groups and firewall policies allow traffic on the following ports:

Prerequisites: Target Host Requirements

Before executing the Supervisor installation, prepare the target system:

1. OTel Collector Binary: Ensure a pre-compiled OpenTelemetry Collector binary is present on the system.
   • Windows default path: C:\Program Files\otelcol\otelcol.exe
   • Linux default path: /usr/local/bin/otelcol
2. Local Administrator Privileges: The installer must register background system services/daemons.
3. Outbound Connectivity: The host must resolve and reach the Management Server over the network via Port 4320 and Port 4321.

1. Management Server Installation

Windows Installation

1. Download the unified executable installer: CollectorCtrl_Setup.exe.
2. Right-click and select Run as Administrator.
3. Choose the installation directory (Defaults to C:\Program Files\CollectorCtrl).
4. Select the Database engine: SQLite (standard) or Postgres (enter connection DSN).
5. The wizard registers a background Windows Service named CollectorCtrlServer.
6. Open your web browser and navigate to https://localhost:4321 (or the server's static IP/hostname).
7. Authenticate using the default credential set:
   • Username: admin
   • Password: admin

Linux Installation

Step 1: Download the release package Download the target architecture release package (e.g., collectorctrl-server_1.1.0_linux_amd64.tar.gz).

Step 2: Extract the archive Extract the archive into a temporary folder:

$tar -xzf collectorctrl-server_1.1.0_linux_amd64.tar.gz

Step 3: Run the automated installer Run the automated installer script as root:

$sudo ./install.sh

[!NOTE] Automated Setup: The install script automatically detects your package manager (apt-get or yum/dnf), downloads and configures PostgreSQL, sets the default credentials (postgres/postgres), provisions the collectorctrl database schema, and registers the server as a systemd service (collectorctrl.service).

Step 4: Access the web console Access the web console at https://YOUR_SERVER_IP:4321.

Step 5: Authenticate Authenticate with the default login credentials (admin / admin).

2. Supervisor Agent Installation

A. Windows Installation (Windows Service)

Our Windows installer handles service registration and registers the agent with the local Service Control Manager (SCM).

1. Execute the agent installer: CollectorCtrl_Supervisor_Setup.exe as an Administrator.
2. Server Connection Page:
   • Server OpAMP Endpoint: Enter the OpAMP endpoint of your CollectorCtrl server (e.g., wss://YOUR_SERVER_IP:4320/v1/opamp).
3. Collector Configuration Page:
   • OpenTelemetry Collector Binary (otelcol.exe): Select the path to your otelcol.exe binary (defaults to C:\otel\otelcol.exe).
   • Initial Collector Config (optional yaml): Select the path to an optional initial configuration YAML file.
4. Finish the wizard. The installer writes the configuration to C:\Program Files\CollectorCtrl Supervisor\supervisor.yaml and starts the CollectorCtrl Supervisor service.

[!NOTE] If your server requires API token authentication or you need to customize settings, edit the generated supervisor.yaml file after installation.

Here is an example of a complete supervisor.yaml configuration for Windows:

server:endpoint: 'wss://YOUR_SERVER_IP:4320/v1/opamp'token: 'YOUR_API_TOKEN'tls:  insecure_skip_verify: true
capabilities:reports_effective_config: truereports_own_metrics: truereports_own_logs: truereports_own_traces: truereports_health: trueaccepts_remote_config: truereports_remote_config: trueaccepts_restart_command: trueaccepts_packages: true
agent:executable: 'C:\Program Files\OpenTelemetry Collector\otelcol.exe'passthrough_logs: trueconfig_files:  - 'C:\Program Files\OpenTelemetry Collector\config.yaml'
storage:directory: 'C:\ProgramData\CollectorCtrlSupervisor\storage'
telemetry:logs:  level: info  output_paths:    - 'C:\ProgramData\CollectorCtrlSupervisor\supervisor.log'

Then restart the CollectorCtrl Supervisor service from the Windows Services console.

Manual PowerShell Registration (Alternative)

If installing via Configuration Management (Ansible, SCCM, Group Policy), you can register the service manually:

# Create the service entry pointing to the supervisor binary and configuration file
PS >New-Service -Name "CollectorCtrlSupervisor" `
PS >          -BinaryPathName '"C:\Program Files\CollectorCtrl Supervisor\supervisor.exe" --config "C:\Program Files\CollectorCtrl Supervisor\supervisor.yaml"' `
PS >          -DisplayName "CollectorCtrl Supervisor" `
PS >          -StartupType Automatic
# Start the service
PS >Start-Service -Name "CollectorCtrlSupervisor"

B. Linux Installation (systemd Daemon)

For Linux systems, the agent configuration is defined in a standard YAML file, and process isolation is handled via systemd.

Step 1: Create the system directory and copy the binary

$sudo mkdir -p /etc/collectorctrl /var/log/collectorctrl
$sudo cp ./collectorctrl-supervisor /usr/local/bin/
$sudo chmod +x /usr/local/bin/collectorctrl-supervisor

Step 2: Create the configuration file Create the configuration file /etc/collectorctrl/supervisor.yaml:

server:endpoint: "wss://YOUR_SERVER_IP:4320/v1/opamp"token: "your_secret_api_token"tls:  insecure_skip_verify: false  ca_file: "/etc/collectorctrl/certs/ca.pem"
capabilities:reports_effective_config: truereports_own_metrics: truereports_own_logs: truereports_own_traces: truereports_health: trueaccepts_remote_config: truereports_remote_config: trueaccepts_restart_command: trueaccepts_packages: true
agent:executable: "/usr/local/bin/otelcol"passthrough_logs: trueconfig_files:  - "/etc/otelcol/config.yaml"
storage:directory: "/var/lib/collectorctrl/storage"
telemetry:logs:  level: info  output_paths:    - "/var/log/collectorctrl/supervisor.log"

Step 3: Create the systemd unit file Create the systemd unit file /etc/systemd/system/collectorctrl-supervisor.service:

[Unit]Description=CollectorCtrl Supervisor AgentAfter=network.target
[Service]Type=simpleUser=rootExecStart=/usr/local/bin/collectorctrl-supervisor --config /etc/collectorctrl/supervisor.yamlRestart=alwaysRestartSec=5LimitNOFILE=65536
[Install]WantedBy=multi-user.target

Step 4: Reload systemd, enable and start the daemon

$sudo systemctl daemon-reload
$sudo systemctl enable --now collectorctrl-supervisor.service

Dynamic Configuration Trigger Mechanics

When an administrator edits a configuration in the UI console and publishes the policy update, the following hot-reload flow occurs:

1. Validation Check: The server compiles the final YAML (resolving targets and merge rules) and executes a dry-run check.
2. File Writing: The Supervisor receives the YAML payload over the OpAMP channel and writes it to the designated config_path.
3. Triggering the Reload:
   • Linux Hosts: The Supervisor sends a SIGHUP signal directly to the OTel Collector process ID, prompting it to hot-reload without tearing down sockets.
   • Windows Hosts: If the OTel Collector binary doesn't support SIGHUP, the Supervisor calls the collector's local administration API reload hook: POST http://localhost:13133/schema/reload If the reload endpoint fails or is disabled, the Supervisor executes a fast process restart (StopProcess then StartProcess) within 150 milliseconds.

Log Directories & Troubleshooting Reference

When debugging pipeline problems, refer to the following log locations:

🏢 On Windows Server

• Server Application Logs: C:\ProgramData\CollectorCtrl\logs\server.log
• Supervisor Service Logs: C:\ProgramData\CollectorCtrlSupervisor\supervisor.log

🐧 On Linux Hosts

• Supervisor Logs: /var/log/collectorctrl/supervisor.log (or retrieve using journalctl -u collectorctrl-supervisor -n 100 --no-pager)
• OTel Collector Log Stream (Observations): /var/log/collectorctrl/otelcol-observations.log