Install on Linux with systemd

Prerequisites

• Operating System: any systemd-based distribution on amd64 or arm64. The PostgreSQL edition's installer supports apt (Ubuntu, Debian) and yum/dnf (RHEL family, Amazon Linux 2023).
• Privileges: Root or sudo access on all nodes
• Network Ports (Server):
  • 4320 (TCP / WSS) — Agent OpAMP communication
  • 4321 (TCP / HTTPS) — Web Console, REST API and package mirror
• Agent Nodes: an OpenTelemetry Collector binary (e.g. /usr/bin/otelcol-contrib) with the health_check extension enabled (port 13133 by default)

Part 1: Install the CollectorCtrl Management Server

Step 1: Download the Server Release

Each release ships two Linux server archives:

• collectorctrl-server-postgres_<version>_linux_<arch>.tar.gz — installs and configures PostgreSQL for you (recommended)
• collectorctrl-server_<version>_linux_<arch>.tar.gz — uses SQLite, or your own PostgreSQL

Download the PostgreSQL edition (use linux_arm64 on ARM hosts). Every file has a matching .sig signature for verifying downloads:

$wget https://github.com/CollectorCtrl/CollectorCtrl/releases/download/v0.6.0-beta/collectorctrl-server-postgres_0.6.0-beta_linux_amd64.tar.gz

Check the releases page for the newest version.

Step 2: Extract and Run the Installer

$tar -xzf collectorctrl-server-postgres_0.6.0-beta_linux_amd64.tar.gz
$sudo ./install.sh

The installer:

• Copies the server and web assets to /opt/collectorctrl-server
• Installs PostgreSQL with your package manager and creates the collectorctrl database and user (PostgreSQL edition)
• Installs and starts the collectorctrl systemd service on ports 4321 (HTTPS console) and 4320 (OpAMP over WSS)

On first start the server creates its certificate authority, server certificate, encryption key and other secrets in its data directory. Back it up and keep it: if it's lost, every agent must re-enroll.

Step 3: Recommended Production Settings

Keep secrets in an environment file that only root and the service can read:

$sudo mkdir -p /etc/collectorctrl /var/lib/collectorctrl
$sudo tee /etc/collectorctrl/server.env >/dev/null <<EOF
$COLLECTORCTRL_MODE=production
$COLLECTORCTRL_DATA_DIR=/var/lib/collectorctrl
$COLLECTORCTRL_JWT_SECRET=$(openssl rand -hex 32)
$COLLECTORCTRL_ENCRYPTION_KEY=$(openssl rand -hex 32)
$EOF
$sudo chmod 600 /etc/collectorctrl/server.env

$sudo systemctl edit collectorctrl
#   [Service]
#   EnvironmentFile=/etc/collectorctrl/server.env

$sudo systemctl daemon-reload && sudo systemctl restart collectorctrl

In production mode the server refuses to start without COLLECTORCTRL_JWT_SECRET and COLLECTORCTRL_ENCRYPTION_KEY, and refuses plain-HTTP listeners on network-facing addresses.

Step 4: Verify the Service

$sudo systemctl status collectorctrl

# Live server logs (the CA fingerprint is printed at start-up):
$sudo journalctl -u collectorctrl -f

Step 5: Sign In to the Web Console

Open https://<YOUR_SERVER>:4321 and sign in as admin / admin. You're asked to choose a new password straight away. To set the initial password instead, start the server for the first time with COLLECTORCTRL_ADMIN_PASSWORD.

Part 2: Enroll Supervisor Agents

Every managed host runs the CollectorCtrl Supervisor next to its OpenTelemetry Collector. The Get Started page generates a one-line command that installs it and enrolls the host securely.

Step 1: Create an Enrollment Token

1. In the Web Console, open Get Started.
2. Create an enrollment token (cce_…). Tokens expire (24 hours by default) and can be limited to a number of hosts.
3. Select Linux, your architecture, the collector binary path (e.g. /usr/bin/otelcol-contrib) and the initial collector config (e.g. /etc/otelcol-contrib/config.yaml).

The generated command already contains the server address, the token and the server's CA fingerprint.

Step 2: Run the Command on the Target Node

Copy the command from Get Started and run it as root on the host. It runs the script served at /api/onboard/linux with options like these:

The script:

1. Downloads the server's CA from /api/onboard/ca.pem and checks its SHA-256 against the pinned fingerprint. It aborts if they differ.
2. Downloads the Supervisor package for the host's OS and architecture from the server's own package mirror (hosts without internet access work), falling back to GitHub Releases.
3. Installs the collectorctrl-supervisor systemd service.
4. Configures wss://<YOUR_SERVER>:4320/v1/opamp with certificate verification on, and hands the enrollment token to the service.

Step 3: Verify the Supervisor

$sudo systemctl status collectorctrl-supervisor

The host appears in Fleet within a few seconds. On first connect the Supervisor exchanges the token for its own credential (cca_…), stored where only the service can read it. The token isn't needed after that. Manage tokens and credentials under Settings → API Tokens → Agent Enrollment.

Service Management Reference

Server Commands

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

Supervisor Agent Commands

$sudo systemctl status collectorctrl-supervisor
$sudo systemctl restart collectorctrl-supervisor
$sudo journalctl -u collectorctrl-supervisor -f

Manual Installation (Golden Images, Ansible)

Use this when you can't run the Get Started command, for example in image builds or configuration-management tools.

$tar -xzf collectorctrl-supervisor_0.6.0-beta_linux_amd64.tar.gz
$sudo ./install.sh \
$--server-endpoint "wss://<YOUR_SERVER>:4320/v1/opamp" \
$--otelcol-binary /usr/bin/otelcol-contrib \
$--otelcol-config /etc/otelcol-contrib/config.yaml

This installs to /opt/collectorctrl-supervisor. The archive's installer doesn't set up trust or enrollment, so then:

1. Download the CA and compare its fingerprint with the one shown in the UI:

$curl -k https://<YOUR_SERVER>:4321/api/onboard/ca.pem -o /opt/collectorctrl-supervisor/collectorctrl-ca.pem
$sha256sum /opt/collectorctrl-supervisor/collectorctrl-ca.pem

2. Point the Supervisor at the server with verification on:

server:
  endpoint: 'wss://YOUR_SERVER:4320/v1/opamp'
  tls:
    insecure_skip_verify: false
    ca_file: '/opt/collectorctrl-supervisor/collectorctrl-ca.pem'

agent:
  executable: '/usr/bin/otelcol-contrib'
  config_files:
    - '/etc/otelcol-contrib/config.yaml'

3. Give the service an enrollment token, then restart it:

$sudo systemctl edit collectorctrl-supervisor
#   [Service]
#   Environment=COLLECTORCTRL_ENROLL_TOKEN=cce_...
$sudo systemctl restart collectorctrl-supervisor

Firewall & Port Reference

UFW (Ubuntu/Debian):

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

Firewalld (RHEL/CentOS/Amazon Linux):

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

Next Steps

• Create your first Fleet Policy — Define targeting rules and deploy configurations fleet-wide
• Upgrade Supervisor Remotely — Remotely push new collector versions with rollback protection
• Configure SSO & Authentication — Integrate OIDC for enterprise team access