Coroot Installation

Coroot Installation | Coroot

System requirements

Coroot relies heavily on eBPF, therefore, the minimum supported Linux kernel version is 4.16.
eBPF-based continuous profiling utilizes CO-RE. CO-RE is supported by most modern Linux distributions, including:
- Ubuntu 20.10 and above
- Debian 11 and above
- RHEL 8.2 and above
Coroot gathers metrics, logs, traces, and profiles, with each telemetry signal associated with containers. In this context, a container refers to a group of processes running within a dedicated cgroup. The following container types are supported:
- Kubernetes Pods using Docker, Containerd, or CRI-O as their runtime environment
- Standalone containers: Docker, Containerd, CRI-O
- Docker Swarm
- Systemd units: any systemd service is also considered as a container
Supported container orchestrators include:
- Kubernetes: Self-managed, EKS (including basic support for AWS Fargate), GKE, AKS, OKE
- OpenShift
- K3s
- MicroK8s
- Docker Swarm
Limitations:
- Coroot doesn't support Docker-in-Docker environments such as MiniKube due to eBPF limitations
- WSL (Windows Subsystem for Linux) is not yet supported

All-in-one installation with Helm

Add the Coroot helm chart repo:

helm repo add coroot https://coroot.github.io/helm-charts
helm repo update coroot

Next, install the chart that includes:

Exposing Coroot for external access:

Visit Coroot at the Ingress URL: http://{{ingressHostname}}

Get the Coroot URL by running these commands in the same shell:

export NODE_PORT=$(kubectl get --namespace coroot -o jsonpath="{.spec.ports[0].nodePort}" services coroot)
export NODE_IP=$(kubectl get nodes --namespace coroot -o jsonpath="{.items[0].status.addresses[0].address}")
echo http://$NODE_IP:$NODE_PORT

Forward the Coroot port to your machine:

kubectl port-forward -n coroot service/coroot 8080:8080

Then, you can access Coroot at http://localhost:8080

Upgrading

To upgrade Coroot to the latest version:

helm repo update coroot
helm upgrade coroot --namespace coroot coroot/coroot

Docker

To install Coroot on a Linux node using Docker Compose, follow these steps:

Step #1: Install Docker Compose (if not installed)

Use the following commands to install Docker Compose on Ubuntu:

apt update
apt install docker-compose-v2

Step #2: Deploy Coroot

To deploy Coroot using Docker Compose, run the following command. Before applying it, you can review the configuration file in Coroot's GitHub repository: docker-compose.yaml

curl -fsS https://raw.githubusercontent.com/coroot/coroot/main/deploy/docker-compose.yaml | docker compose -f - up -d

Step #3: Validate the deployment

Ensure that the Coroot containers are running by executing the following command:

docker ps

You should see an output similar to this if the deployment is successful:

CONTAINER ID   IMAGE                               COMMAND                  CREATED          STATUS          PORTS                                          NAMES
9451a61a8136   ghcr.io/coroot/coroot:latest        "/opt/coroot/coroot …"   33 seconds ago   Up 31 seconds   0.0.0.0:8080->8080/tcp, :::8080->8080/tcp      root-coroot-1
e81fdd93cffc   clickhouse/clickhouse-server:24.3   "/entrypoint.sh"         33 seconds ago   Up 32 seconds   8123/tcp, 9009/tcp, 127.0.0.1:9000->9000/tcp   root-clickhouse-1
9e8b809db618   prom/prometheus:v2.45.4             "/bin/prometheus --c…"   33 seconds ago   Up 32 seconds   127.0.0.1:9090->9090/tcp                       root-prometheus-1
6431fb47f21a   ghcr.io/coroot/coroot-node-agent    "coroot-node-agent -…"   3 hours ago      Up 32 seconds                                                  root-coroot-node-agent-1

Step #4: Accessing Coroot

If you installed Coroot on your desktop machine, you can access it at http://localhost:8080/.
If Coroot is deployed on a remote node, replace <NODE_IP_ADDRESS> with the IP address of the node in the following URL: http://<NODE_IP_ADDRESS>:8080/.

Docker Swarm

To deploy Coroot to a Docker Swarm cluster, follow these steps:

Step #1: Initialize Docker Swarm

If you haven't already initialized Docker Swarm on your manager node, run the following command on the manager node:

docker swarm init

This initializes a new Docker Swarm and joins the current node as a manager.

Step #2: Deploy the Coroot Stack

Deploy the Coroot stack to your cluster by running the following command on the manager node. Before applying, you can review the configuration file in Coroot's GitHub repository: docker-swarm-stack.yaml

curl -fsS https://raw.githubusercontent.com/coroot/coroot/main/deploy/docker-swarm-stack.yaml | docker stack deploy -c - coroot

Step #3: Validate the deployment

After deploying the stack, you can use docker stack ls to list the deployed stacks in your Docker Swarm cluster. Here's an example of how the output might look:

NAME      SERVICES
coroot    3

Step #4: Installing coroot-node-agent

Since Docker Swarm doesn't support privileged containers, you'll have to manually deploy coroot-node-agent on each cluster node. Just replace <NODE_IP> with any node's IP address in the Docker Swarm cluster.

docker run --detach --name coroot-node-agent \
  --pull=always \
  --privileged --pid host \
  -v /sys/kernel/tracing:/sys/kernel/tracing:rw \
  -v /sys/kernel/debug:/sys/kernel/debug:rw \
  -v /sys/fs/cgroup:/host/sys/fs/cgroup:ro \
  ghcr.io/coroot/coroot-node-agent \
  --cgroupfs-root=/host/sys/fs/cgroup \
  --collector-endpoint=http://<NODE_IP>:8080

Step #5: Accessing Coroot

Access Coroot through any node in your Docker Swarm cluster using its published port: http://<node_ip>:8080.

Ubuntu / Debian

To deploy Coroot on a Ubuntu or Debian node, follow these steps:

Step #1: Installing ClickHouse

sudo apt install -y apt-transport-https ca-certificates curl gnupg
curl -fsSL 'https://packages.clickhouse.com/rpm/lts/repodata/repomd.xml.key' | sudo gpg --dearmor -o /usr/share/keyrings/clickhouse-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/clickhouse-keyring.gpg] https://packages.clickhouse.com/deb stable main" | sudo tee /etc/apt/sources.list.d/clickhouse.list
sudo apt update
sudo DEBIAN_FRONTEND=noninteractive apt install -y clickhouse-server clickhouse-client
sudo service clickhouse-server start

Step #2: Installing Prometheus

Coroot requires Prometheus with support for Remote Write Receiver, which has been available since v2.25.0.

sudo apt install -y prometheus
sudo service prometheus start

Enable Remote Write Receiver in Prometheus by adding the --enable-feature=remote-write-receiver argument to the /etc/default/prometheus file:

# Set the command-line arguments to pass to the server.
# Due to shell escaping, to pass backslashes for regexes, you need to double
# them (\\d for \d). If running under systemd, you need to double them again
# (\\\\d to mean \d), and escape newlines too.
ARGS="--enable-feature=remote-write-receiver"

Restart Prometheus:

sudo service prometheus restart

Step #3: Installing Coroot

curl -sfL https://raw.githubusercontent.com/coroot/coroot/main/deploy/install.sh | \
    BOOTSTRAP_PROMETHEUS_URL="http://127.0.0.1:9090" \
    BOOTSTRAP_REFRESH_INTERVAL=15s \
    BOOTSTRAP_CLICKHOUSE_ADDRESS=127.0.0.1:9000 \
    sh -

Step #4: Installing coroot-node-agent

curl -sfL https://raw.githubusercontent.com/coroot/coroot-node-agent/main/install.sh | \
    COLLECTOR_ENDPOINT=http://127.0.0.1:8080 \
    SCRAPE_INTERVAL=15s \
    sh -

Step #5: Accessing Coroot

Access Coroot at: http://<node_ip>:8080.

CentOS / RHEL

To deploy Coroot on a CentOS or RHEL node, follow these steps:

Step #1: Installing ClickHouse

sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://packages.clickhouse.com/rpm/clickhouse.repo
sudo yum install -y clickhouse-server clickhouse-client
sudo systemctl enable clickhouse-server
sudo systemctl start clickhouse-server

Step #2: Installing Prometheus

Coroot requires Prometheus with support for Remote Write Receiver, which has been available since v2.25.0. Unfortunately, there is no official Prometheus RPM package. Here is a step-by-step guide on how to install Prometheus manually, including creating a systemd service file for it.

Create a Prometheus user:

sudo useradd --no-create-home --shell /bin/false prometheus

Navigate to the Prometheus download page, and find the URL for the latest version of Prometheus for Linux and your architecture. Use wget to download it:

wget https://github.com/prometheus/prometheus/releases/download/v2.51.2/prometheus-2.51.2.linux-amd64.tar.gz

Extract the downloaded tarball and move the binary to /usr/local/bin/:

sudo yum -y install tar
tar xvfz prometheus-2.51.2.linux-amd64.tar.gz
sudo cp prometheus-2.51.2.linux-amd64/prometheus /usr/local/bin/

Create directories for Prometheus configuration files and data:

sudo mkdir /etc/prometheus
sudo mkdir /var/lib/prometheus
sudo chown -R prometheus:prometheus /etc/prometheus /var/lib/prometheus

Create a Prometheus configuration file:

sudo cat <<EOF >/etc/prometheus/prometheus.yml
global:
  scrape_interval: 15s
EOF

Create a systemd service file for Prometheus:

sudo cat <<EOF >/etc/systemd/system/prometheus.service
[Unit]
Description=Prometheus
After=network.target

[Service]
User=prometheus
Group=prometheus
Type=simple
ExecStart=/usr/local/bin/prometheus --config.file /etc/prometheus/prometheus.yml --storage.tsdb.path /var/lib/prometheus --enable-feature=remote-write-receiver

[Install]
WantedBy=multi-user.target
EOF

Reload systemd to load the new service and start Prometheus:

sudo systemctl daemon-reload
sudo systemctl start prometheus
sudo systemctl enable prometheus

Step #3: Installing Coroot

curl -sfL https://raw.githubusercontent.com/coroot/coroot/main/deploy/install.sh | \
    BOOTSTRAP_PROMETHEUS_URL="http://127.0.0.1:9090" \
    BOOTSTRAP_REFRESH_INTERVAL=15s \
    BOOTSTRAP_CLICKHOUSE_ADDRESS=127.0.0.1:9000 \
    sh -

Step #4: Installing coroot-node-agent

curl -sfL https://raw.githubusercontent.com/coroot/coroot-node-agent/main/install.sh | \
    COLLECTOR_ENDPOINT=http://127.0.0.1:8080 \
    SCRAPE_INTERVAL=15s \
    sh -

Step #5: Accessing Coroot

Access Coroot at: http://<node_ip>:8080.

CLI arguments

Argument Environment variable Default value Description {{a.name}} {{a.env}} {{a.def}}

We're sorry but Coroot doesn't work properly without JavaScript enabled. Please enable it to continue.