Install on Linux with systemd

Deploy CollectorCtrl on Ubuntu, Debian, RHEL, CentOS, or Amazon Linux with the automated install script. 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+, CentOS 8+, or Amazon Linux 2023
• Root or sudo access
• OpenTelemetry Collector binary available (/usr/local/bin/otelcol) on agent nodes
• Ports 4320 and 4321 available

Part 1: Install the Management Server

Step 1: Download and Extract the Release

# For x86_64 (Intel/AMD) — PostgreSQL edition
# Note: use an explicit release tag — /releases/latest/ is not available while
# releases are published as betas. Check the releases page for the newest tag:
# https://github.com/CollectorCtrl/CollectorCtrl/releases
$wget https://github.com/CollectorCtrl/CollectorCtrl/releases/download/v0.2.6-beta/collectorctrl-server-postgres_0.2.6_linux_amd64.tar.gz
$tar -xzf collectorctrl-server-postgres_0.2.6_linux_amd64.tar.gz
$cd collectorctrl-server_linux_amd64

# For ARM64 (AWS Graviton, Raspberry Pi), download the linux_arm64 tarball instead

Step 2: Run the Automated Installer

$sudo ./install.sh

That's it — one command. The install script automatically:

• Detects your package manager (apt-get or yum/dnf)
• Installs PostgreSQL (PostgreSQL edition) and creates the collectorctrl database and user
• Auto-configures pg_hba.conf for local authentication (scram-sha-256 / trust) on RHEL, Amazon Linux, Ubuntu, and Debian
• Writes the connection string (postgres://postgres:[email protected]:5432/collectorctrl?sslmode=disable) into the systemd unit
• Installs and enables the systemd service at /etc/systemd/system/collectorctrl.service
• Starts the server on HTTP port 4321

Step 3: Verify the Service

$sudo systemctl status collectorctrl

# Live logs:
$sudo journalctl -u collectorctrl -f

Step 4: Access the Dashboard

Open your browser and navigate to 👉 http://YOUR_SERVER_IP:4321

Default credentials:

• Username: admin
• Password: admin

Part 2: Install the Supervisor Agent

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

curl -sfL http://YOUR_SERVER_IP:4321/api/onboard/linux | sudo bash

Step 1: Download and Extract

# Use an explicit release tag (see the releases page for the newest):
# https://github.com/CollectorCtrl/CollectorCtrl/releases
$wget https://github.com/CollectorCtrl/CollectorCtrl/releases/download/v0.2.6-beta/collectorctrl-supervisor_0.2.6_linux_amd64.tar.gz
$tar -xzf collectorctrl-supervisor_0.2.6_linux_amd64.tar.gz
$cd collectorctrl-supervisor_linux_amd64

Step 2: Run the Interactive Installer

$sudo ./install.sh

When prompted, enter your Management Server's OpAMP endpoint:

$Management Server Endpoint [ws://localhost:4320/v1/opamp]: ws://YOUR_SERVER_IP:4320/v1/opamp

The installer writes supervisor.yaml, registers the collectorctrl-supervisor systemd service, and starts it.

Step 3: Verify the Agent Appears

$sudo systemctl status collectorctrl-supervisor

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

Configuration Reference (Manual Setup)

Only needed if you skip the install scripts or want to customize the setup.

supervisor.yaml

server:
  endpoint: 'ws://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: true
  reports_own_metrics: true
  reports_own_logs: true
  reports_own_traces: true
  reports_health: true
  accepts_remote_config: true
  reports_remote_config: true
  accepts_restart_command: true
  accepts_packages: true

agent:
  executable: '/usr/local/bin/otelcol'
  passthrough_logs: true
  config_files:
    - '/etc/otelcol/config.yaml'

storage:
  directory: '/var/lib/collectorctrl/storage'

telemetry:
  logs:
    level: info
    output_paths:
      - '/var/log/collectorctrl/supervisor.log'

systemd unit for the Supervisor

[Unit]
Description=CollectorCtrl Supervisor Agent
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/collectorctrl-supervisor --config /etc/collectorctrl/supervisor.yaml
Restart=always
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

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

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=postgres://postgres:postgres@postgres:5432/collectorctrl?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