Coroot eBPF Observability on AWS User Guide

Overview

Coroot Community Edition is an open source observability and application performance monitoring (APM) platform built on eBPF. A zero-instrumentation node agent captures metrics, distributed traces, logs and continuous CPU profiles straight from the Linux kernel, and Coroot correlates them into automatic service maps, health and latency SLOs, incident detection and root-cause hints, all explorable from a built-in web dashboard. It bundles its own metrics store (Prometheus) and telemetry store (ClickHouse) so a single instance gives you a full picture of how your services talk to each other and where time and errors are spent, without adding tracing libraries to your code.

The cloudimg image runs the pinned Coroot Community Edition 1.23.3 stack as official upstream containers under one systemd service, then locks it down for a marketplace appliance. The Coroot server is bound to loopback 127.0.0.1:8080 and fronted by an nginx reverse proxy on port 80, while the bundled Prometheus and ClickHouse run on a private Docker network and are never published to a host port. Coroot has a built-in admin login with no default password, so a unique admin password is generated on the first boot of your instance and used to seed the admin account before the port is ever public. The privileged eBPF node agent ships host CPU, memory, disk, network, container and process telemetry into Coroot automatically. All container data lives on a dedicated, independently-resizable EBS volume mounted at the Docker data-root, keeping telemetry storage off the OS disk. Backed by 24/7 cloudimg support.

What is included:

• Coroot Community Edition 1.23.3 (server plus web dashboard) running as the coroot systemd service via docker compose
• A bundled Prometheus (metrics) and ClickHouse (traces, logs and profiles), both on a private network with no host port
• The privileged eBPF coroot-node-agent collecting host and process telemetry with zero instrumentation
• nginx on :80 fronting the dashboard, with Coroot bound to loopback only and an unauthenticated /healthz for load-balancer probes
• A per-instance admin password generated on first boot and seeded into Coroot, with no default login baked into the image
• A dedicated gp3 EBS data volume mounted at /var/lib/docker for all telemetry storage
• A fully patched Ubuntu 24.04 LTS base

Coroot is a trademark of Coroot, Inc. This image is provided by cloudimg and is not affiliated with, endorsed by, or sponsored by Coroot, Inc.

Prerequisites

• An AWS account and permission to launch EC2 instances and subscribe to AWS Marketplace products
• An EC2 key pair for SSH access
• A security group allowing inbound TCP 22 (SSH) and 80 (the web dashboard), and optionally 443 if you add TLS
• A recommended instance type of m5.large (2 vCPU, 8 GiB) or larger, because the bundled ClickHouse telemetry store benefits from memory headroom

Connecting to your instance

Each AMI variant logs in over SSH as its distribution's default user:

ssh ubuntu@<instance-public-ip>

Step 1 - Subscribe and launch from AWS Marketplace

Open the product's AWS Marketplace listing, choose Continue to Subscribe, accept the terms, then Continue to Configuration and Continue to Launch. Pick the m5.large (or larger) instance type, your VPC subnet, your EC2 key pair, and a security group that allows inbound SSH (22) and HTTP (80). Launch the instance.

Step 2 - Launch with the AWS CLI

aws ec2 run-instances \
  --image-id <coroot-ami-id> \
  --instance-type m5.large \
  --key-name <your-key-pair> \
  --security-group-ids <sg-with-22-and-80> \
  --subnet-id <your-subnet> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=coroot}]'

Find the AMI id on the Marketplace listing's launch page for your region.

Step 3 - Connect to your instance

ssh ubuntu@<instance-public-ip>

Step 4 - Confirm the services are running

systemctl is-active docker.service coroot.service nginx.service

All three report active. The coroot.service unit runs the whole stack with docker compose: the Coroot server on the loopback address 127.0.0.1:8080, the bundled Prometheus and ClickHouse on a private Docker network, and the privileged eBPF node agent. nginx fronts the dashboard on port 80.

Step 5 - Retrieve your admin password

Coroot has a built-in admin login. The username is admin and a unique password is generated on the first boot of your instance, used to seed the admin account, and written to a root-only file:

sudo cat /root/coroot-credentials.txt

This file contains coroot.username, coroot.password and the coroot.url to open in a browser. There is no default login: the admin account only exists with the per-instance password, so no two deployments share a credential and nothing usable is baked into the image. Store the password somewhere safe.

Step 6 - Confirm the health endpoint

nginx serves an unauthenticated health endpoint for load balancers and probes:

curl -s http://localhost/healthz

It returns ok. Coroot's own /health endpoint is also unauthenticated and returns 200, so either is safe for an Application Load Balancer health check. Everything else requires the admin login.

Step 7 - Confirm the authentication gate

Coroot's API sits behind the admin session. The following reads the per-instance password from the credentials file and proves the round-trip: an unauthenticated API call is rejected with 401, a wrong-password login is rejected, the correct password logs in and receives a coroot_session cookie, and an authenticated API call with that cookie returns 200:

PW=$(sudo sed -n 's/^coroot.password=//p' /root/coroot-credentials.txt)
echo "health  : $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1/health)"
echo "unauth  : $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1/api/project/)"
echo "wrongpw : $(curl -s -o /dev/null -w '%{http_code}' -X POST -H 'Content-Type: application/json' -d '{"email":"admin","password":"wrong-password"}' http://127.0.0.1/api/login)"
curl -s -o /dev/null -c /tmp/coroot.cookie -X POST -H 'Content-Type: application/json' \
  -d "{\"email\":\"admin\",\"password\":\"$PW\"}" http://127.0.0.1/api/login
echo "login   : $(curl -s -o /dev/null -w '%{http_code}' -c /tmp/coroot.cookie -X POST -H 'Content-Type: application/json' -d "{\"email\":\"admin\",\"password\":\"$PW\"}" http://127.0.0.1/api/login)"
echo "authed  : $(curl -s -o /dev/null -w '%{http_code}' -b /tmp/coroot.cookie http://127.0.0.1/api/project/)"

It prints health : 200, unauth : 401, wrongpw : 404, login : 200, then authed : 200. The API is only reachable with the per-instance admin session because Coroot itself is bound to loopback and nginx is the only way in.

Step 8 - Confirm the eBPF node agent is collecting telemetry

The bundled node agent uses eBPF to collect metrics, traces, logs and CPU profiles from the kernel with no instrumentation. Once logged in, the API reports the nodes it has discovered:

PW=$(sudo sed -n 's/^coroot.password=//p' /root/coroot-credentials.txt)
curl -s -c /tmp/coroot.cookie -o /dev/null -X POST -H 'Content-Type: application/json' \
  -d "{\"email\":\"admin\",\"password\":\"$PW\"}" http://127.0.0.1/api/login
PID=$(curl -s -b /tmp/coroot.cookie http://127.0.0.1/api/user | python3 -c 'import json,sys; print(json.load(sys.stdin)["projects"][0]["id"])')
curl -s -b /tmp/coroot.cookie "http://127.0.0.1/api/project/$PID/overview/nodes" \
  | python3 -c 'import json,sys; d=json.load(sys.stdin); print("node agent status:", d["context"]["status"]["node_agent"])'

It prints node agent status: {'status': 'ok', 'nodes': 1}. As the agent reports in, the service map and dashboards in the web UI fill with the host, its processes and their interconnections, usually within a couple of minutes.

Step 9 - Sign in to the Coroot dashboard

Open coroot.url from your credentials file (http://<instance-public-ip>/) in a browser. Coroot presents a sign-in page; enter the username admin and the per-instance password from your credentials file, then click Log In.

Step 10 - Explore the Applications overview

After signing in, Coroot opens the Applications overview. It lists every service the eBPF agent has discovered, each with a health indicator and columns for its SLO, running instances, CPU, memory, storage and network, all built automatically from kernel-level telemetry with no instrumentation added to your code.

Step 11 - Follow the service map

The Service Map draws the discovered services and the calls between them as a live topology, so you can see how requests flow through your system and where latency and errors originate, again reconstructed automatically from eBPF telemetry.

Step 12 - Inspect an application's dashboard and SLOs

Selecting an application opens its dashboard: the instance topology, its dependencies, and the availability and latency SLOs Coroot tracks automatically, with tabs for instances, CPU, memory, storage and network charts. The Traces, Logs and Profiling sections expose the distributed traces, logs and continuous CPU profiles Coroot stores in the bundled ClickHouse.

Step 13 - Inspect node and infrastructure metrics

The Nodes view lists every host the agent runs on with its status, compute, availability zone and CPU, memory, disk and network metrics collected over eBPF. Selecting a node drills into detailed per-host charts.

Maintenance

Change the admin password. Sign in to the dashboard, open the user menu and change the password there, or reset it from the server:

sudo docker exec -it coroot-coroot-1 coroot set-admin-password

Adjust telemetry retention. Traces, logs, profiles and metrics retention are configured in the dashboard under Project Settings. The bundled Prometheus keeps metrics for 30 days by default.

Point more agents at Coroot. To observe additional hosts or a Kubernetes cluster, install the Coroot node agent (or the Coroot Operator) on them and set its collector endpoint to http://<instance-public-ip>/. See the Coroot documentation for agent installation on other platforms.

Grow the telemetry disk. All container data lives on the dedicated EBS volume at /var/lib/docker. Grow it in the EC2 console (Elastic Volumes) and extend the filesystem with sudo resize2fs as your retention needs increase.

Add a domain and TLS. For production, point a DNS name at the instance and terminate HTTPS at nginx with a certificate from Let's Encrypt (certbot --nginx) so the dashboard is served over https://.

Service management.

systemctl status coroot nginx --no-pager
sudo docker compose -f /etc/coroot/compose.yaml ps

Coroot's containers log to the Docker journal; view them with sudo docker compose -f /etc/coroot/compose.yaml logs.

Support

This image is maintained by cloudimg with 24/7 support. If you need help deploying or operating Coroot on AWS, contact the cloudimg team at support@cloudimg.co.uk or through the AWS Marketplace listing. For Coroot's features, agents and configuration, see the Coroot documentation.