Getting Started with Coroot: Docker Deployment Guide

🐳 Deploying Coroot with Docker: A Step-by-Step Guide

I'll be honest: when I first looked at Coroot's docs, I was intimidated. ClickHouse, Prometheus, eBPF agents, cluster operators — it sounded like a full-time DevOps job just to get started. But after actually setting it up, I realized the Docker deployment is surprisingly straightforward.

In this guide, I'll walk through deploying Coroot Community Edition with Docker Compose, and share the mistakes I made so you don't repeat them.

📋 Prerequisites

Before we start, you'll need:

• Docker Engine 24+ and Docker Compose v2
• A Linux host (tested on Ubuntu 22.04 and 24.04)
• At least 4GB RAM and 2 vCPUs for the full stack
• Port 8080 free (Coroot's web UI) and port 9090 (Prometheus)

If you're on macOS or Windows, you'll need a Linux VM — Coroot's eBPF-based node agent requires a Linux kernel with BPF support.

⚡ Quick Start with the Official Compose File

Coroot provides an official docker-compose.yml in their repo, but it includes everything — Prometheus, ClickHouse, node-agent, and cluster-agent. For a quick evaluation, I'd recommend starting with just the core services first.

Clone the repo and use their deploy file:

git clone https://github.com/coroot/coroot.git
cd coroot/deploy
docker compose up -d

Wait time: About 2-3 minutes for everything to start. ClickHouse takes the longest. Grab a coffee.

🔧 My First Mistake: Port Conflicts

I ran docker-compose up without checking port availability. ClickHouse uses 9000 and 8123, Prometheus uses 9090 — and I had something else on 9000. The compose file mapping is 127.0.0.1:9000:9000 which only binds to localhost, so it's secure, but if something's already there, ClickHouse fails silently.

Check first:

sudo lsof -i :9000 -i :9090 -i :8080

If any are in use, you can either stop the conflicting service or edit the docker-compose.yml ports section before starting.

🗺️ Accessing the Dashboard

Once everything's running, open http://YOUR_SERVER_IP:8080 in your browser. You should see Coroot's Dashboard with the Service Map.

⚠️ If you see a blank page or "Waiting for data": This caught me out too. Coroot needs about 30-60 seconds to discover services. If it stays blank longer, check that Prometheus is healthy:

curl http://localhost:9090/-/healthy

If Prometheus returns "Prometheus is Healthy", the issue is likely ClickHouse. Check:

curl http://localhost:8123/ping

🧪 Installing the Node Agent (Optional but Recommended)

The docker-compose.yml already includes a node-agent service, but it needs privileged access for eBPF. On some systems, AppArmor or SELinux blocks it. If you see permission errors in the node-agent logs:

docker logs coroot-node-agent-1 | grep -i error

The fix is to add security_opt: to the compose file:

services:
  node-agent:
    security_opt:
      - apparmor:unconfined
      - seccomp:unconfined

This is safe because the agent only reads kernel tracing data — it doesn't modify anything.

📊 First Impressions: What I Learned in 30 Minutes

Once Coroot was up and collecting data, here's what it showed me within half an hour:

• 3 unknown services — containers I didn't know were still running on the cluster
• 1 connection leak — a service was hammering ClickHouse with 200+ connections
• 2 SLO violations — services that were below their latency targets

The AI root cause analysis flagged the connection leak automatically and showed the specific SQL query responsible. That alone saved me hours of digging through slow query logs.

🎯 Performance Tips

✅ Final Thoughts

Deploying Coroot with Docker took me about 15 minutes including troubleshooting. The compose file from their repo works out of the box on a clean Ubuntu server. The eBPF-based discovery is genuinely impressive — it found services and dependencies I didn't know existed. If you're running a Kubernetes cluster or a microservices stack and you're tired of cobbling together 5 monitoring tools, give Coroot a try.

One thing I'd add: The documentation has a "Community Edition" quick-start, but it's Kubernetes-focused. The Docker Compose path works better for smaller deployments, so use deploy/docker-compose.yml from the repo, not the Helm chart, unless you're on K8s.