Quick Start with Docker

Get CollectorCtrl running locally in under 5 minutes. This is the fastest way to evaluate the platform before committing to a production deployment.

Ports at a Glance

CollectorCtrl exposes exactly two ports:

Prerequisites

• Docker installed on your machine (Get Docker)
• Ports 4320 and 4321 available on localhost

Step 1: Run the Management Server

Pick whichever option you prefer — both do the same thing.

Option A: Docker Run (quickest)

$docker run -d \
$  --name collectorctrl \
$  --restart always \
$  -p 4320:4320 \
$  -p 4321:4321 \
$  -v collectorctrl-data:/opt/collectorctrl \
$  ghcr.io/collectorctrl/collectorctrl-server:latest

The -v collectorctrl-data:/opt/collectorctrl flag persists your data (database, configs) in a named Docker volume, so nothing is lost when the container is replaced or upgraded.

Option B: Docker Compose

Create a docker-compose.yml file:

version: '3.8'

services:
  collectorctrl:
    image: ghcr.io/collectorctrl/collectorctrl-server:latest
    container_name: collectorctrl
    restart: always
    ports:
      - '4320:4320' # OpAMP WebSocket
      - '4321:4321' # Web Dashboard & REST API
    volumes:
      - collectorctrl-data:/opt/collectorctrl

volumes:
  collectorctrl-data:

Then start the service:

$docker compose up -d

Step 2: Open the Dashboard

Navigate to 👉 http://localhost:4321 in your browser (or http://<your-server-ip>:4321 if Docker runs on another machine).

Default credentials:

• Username: admin
• Password: admin — you will be prompted to change it on first login

Step 3: Install a Supervisor Agent

Now connect an OpenTelemetry Collector to your server. The Supervisor agent runs alongside your collector and manages its lifecycle.

Option A: Get Started Wizard (recommended)

Open Get Started (🧭) in the dashboard sidebar. It generates the exact install command for your platform — with the server address, latest release package, and architecture already filled in — and shows a live indicator that turns green the moment your agent checks in.

For a Linux/macOS test machine with sudo, the generated one-liner looks like:

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

Option B: Manual setup

On Linux/macOS (test machine)

First, create a supervisor config file:

$mkdir -p ~/.config/collectorctrl

$cat > ~/.config/collectorctrl/supervisor.yaml << 'EOF'
$server:
$  endpoint: 'ws://localhost:4320/v1/opamp'
$  tls:
$    insecure_skip_verify: true

$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

$agent:
$  executable: '/usr/local/bin/otelcol'
$  passthrough_logs: true

$storage:
$  directory: '~/.local/share/collectorctrl/storage'

$telemetry:
$  logs:
$    level: info
$EOF

Then run the Supervisor:

# Download the supervisor package for your platform (example: Linux AMD64)
# 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.
$curl -sfL -o supervisor.tar.gz \
$  https://github.com/CollectorCtrl/CollectorCtrl/releases/download/v0.2.6-beta/collectorctrl-supervisor_0.2.6_linux_amd64.tar.gz

$tar -xzf supervisor.tar.gz
$chmod +x collectorctrl-supervisor
$./collectorctrl-supervisor --config ~/.config/collectorctrl/supervisor.yaml

On Windows

1. Download the supervisor package collectorctrl-supervisor_0.2.6_windows_amd64.exe from the releases page (pick the newest release tag)
2. Create supervisor.yaml in the same folder:

server:
  endpoint: 'ws://localhost:4320/v1/opamp'
  tls:
    insecure_skip_verify: true

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

agent:
  executable: 'C:\Program Files\otelcol\otelcol.exe'
  passthrough_logs: true

storage:
  directory: 'C:\ProgramData\CollectorCtrlSupervisor\storage'

telemetry:
  logs:
    level: info

3. Run: collectorctrl-supervisor_0.2.6_windows_amd64.exe --config supervisor.yaml

Step 4: See Your Agent in the Dashboard

Go back to http://localhost:4321. Within a few seconds, your agent should appear in the Fleet Overview.

You'll see:

• Hostname and OS information
• Health status (Healthy/Unhealthy/Disconnected)
• Current config hash
• Service name and version

Step 5: Create Your First Policy (Optional)

1. Navigate to Fleet → Policies in the sidebar
2. Click New Policy
3. Give it a name like default-config
4. In the Target Selector, use:

   {"matchLabels": {}}
   

   (empty = targets all agents)
5. Paste a basic OpenTelemetry Collector config in the Main Config editor:

   receivers:
     otlp:
       protocols:
         grpc:
           endpoint: 0.0.0.0:4317
         http:
           endpoint: 0.0.0.0:4318
   
   processors:
     batch:
   
   exporters:
     debug:
       verbosity: detailed
   
   service:
     pipelines:
       traces:
         receivers: [otlp]
         processors: [batch]
         exporters: [debug]
   

6. Click Publish

The config will be pushed to your agent via OpAMP. The Supervisor will apply it in place with a fast, supervised restart — you'll see the agent cycle briefly and come back healthy.

Next Steps

• Install on Windows Server for production
• Install on Linux with systemd for production
• Learn about Fleet Policies
• Read the full documentation

Clean Up

To stop and remove the Docker container:

$docker stop collectorctrl && docker rm collectorctrl

# Also delete the stored data (optional):
$docker volume rm collectorctrl-data