Install on Linux with systemd

Deploy CollectorCtrl on Ubuntu, Debian, RHEL, or CentOS with native systemd integration. The Management Server runs as a systemd unit, and the Supervisor agent runs as a daemon on each target node.

Prerequisites

• Ubuntu 18.04+, Debian 10+, RHEL 8+, or CentOS 8+
• Root or sudo access
• OpenTelemetry Collector binary available (/usr/local/bin/otelcol)
• Ports 4320 and 4321 available

Part 1: Install the Management Server

Step 1: Download the Release

# For x86_64 (Intel/AMD)
$wget https://github.com/CollectorCtrl/CollectorCtrl/releases/latest/download/collectorctrl-server_1.1.10_linux_amd64.tar.gz
# For ARM64 (AWS Graviton, Raspberry Pi)
# wget https://github.com/CollectorCtrl/CollectorCtrl/releases/latest/download/collectorctrl-server_1.1.10_linux_arm64.tar.gz

Step 2: Extract and Install

$tar -xzf collectorctrl-server_1.1.10_linux_amd64.tar.gz
$cd collectorctrl-server_1.1.10_linux_amd64
$sudo ./install.sh

The install script automatically:

• Detects your package manager (apt-get or yum/dnf)
• Installs and configures PostgreSQL (if selected)
• Creates the collectorctrl database and user
• Registers the collectorctrl-server systemd service
• Starts the service

Step 3: Verify the Service

$sudo systemctl status collectorctrl-server
$sudo journalctl -u collectorctrl-server -f

Step 4: Access the Dashboard

Open your browser and navigate to:

http://YOUR_SERVER_IP:4321

Default credentials:

• Username: admin
• Password: admin

⚠️ Change the default password immediately after first login.

Part 2: Install the Supervisor Agent

Repeat these steps on every Linux node where you want to manage an OpenTelemetry Collector.

Step 1: Create Directories and Install Binary

$sudo mkdir -p /etc/collectorctrl /var/log/collectorctrl
# Download the supervisor for your architecture
$wget https://github.com/CollectorCtrl/CollectorCtrl/releases/latest/download/collectorctrl-supervisor_1.1.10_linux_amd64.tar.gz
$tar -xzf collectorctrl-supervisor_1.1.10_linux_amd64.tar.gz
$sudo cp ./collectorctrl-supervisor /usr/local/bin/
$sudo chmod +x /usr/local/bin/collectorctrl-supervisor

Step 2: Create the Supervisor Configuration

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"

Tip: Generate an API token from the Admin UI under Settings → API Tokens.

Step 3: Create the systemd Unit File

[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: Enable and Start the Service

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

Step 5: Verify the Agent Appears

Within 30 seconds, the agent should appear in the Fleet Overview at http://YOUR_SERVER_IP:4321.

Docker Compose Deployment (Alternative)

For containerized deployments, use this docker-compose.yml:

version: '3.8'
services:collectorctrl-server:  image: ghcr.io/collectorctrl/collectorctrl-server:latest  ports:    - "4320:4320"    - "4321:4321"  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  volumes:    - postgres_data:/var/lib/postgresql/data  healthcheck:    test: ["CMD-SHELL", "pg_isready -U postgres"]    interval: 5s    timeout: 5s    retries: 5
volumes:postgres_data:

Start with:

$docker-compose up -d

Database Sizing Guidelines

Firewall Requirements

No inbound ports needed on agent machines — they connect outbound to the server.

UFW example:

$sudo ufw allow 4320/tcp
$sudo ufw allow 4321/tcp

Firewalld example:

$sudo firewall-cmd --permanent --add-port=4320/tcp
$sudo firewall-cmd --permanent --add-port=4321/tcp
$sudo firewall-cmd --reload

Log Locations

Next Steps

• Create your first Fleet Policy
• Upgrade agents remotely
• Set up SSO