Skip to content
Klutch.sh Docs

Deploying Coroot

Introduction

Coroot is an open-source monitoring and observability platform designed to help you monitor and troubleshoot your applications with zero instrumentation. It provides comprehensive insights into your infrastructure by analyzing metrics, logs, and traces to automatically identify issues and their root causes. Built to work seamlessly with Prometheus and other cloud-native technologies, Coroot transforms raw telemetry data into actionable insights.

Coroot stands out for its:

  • Zero Instrumentation: Monitor applications without code changes or agent installation
  • Root Cause Analysis: Automatically identify and diagnose issues in your infrastructure
  • Service Map: Visual representation of your microservices and their dependencies
  • Cost Optimization: Track and optimize your infrastructure costs
  • ClickHouse Backend: High-performance data storage for metrics and traces
  • Prometheus Integration: Native support for Prometheus metrics
  • Alert Management: Intelligent alerting with context-rich notifications
  • Beautiful Dashboards: Pre-built dashboards for common services and applications

This comprehensive guide walks you through deploying Coroot on Klutch.sh using Docker, including detailed installation steps, sample configurations, persistent storage setup, and production-ready best practices.

Prerequisites

Before you begin, ensure you have the following:

  • A Klutch.sh account
  • A GitHub account with a repository for your Coroot project
  • Docker installed locally for testing (optional but recommended)
  • Basic understanding of Docker, Prometheus, and observability concepts
  • (Optional) A Prometheus instance or metrics source to monitor

Installation and Setup

Step 1: Create Your Project Directory

First, create a new directory for your Coroot deployment project:

Terminal window
mkdir coroot-klutch
cd coroot-klutch
git init

Step 2: Create the Dockerfile

Create a Dockerfile in your project root directory. This will define your Coroot container configuration:

FROM ghcr.io/coroot/coroot:latest


# Expose the default Coroot port
EXPOSE 8080


# Set environment variables
ENV BOOTSTRAP_CLICKHOUSE_ADDRESS=localhost:9000
ENV BOOTSTRAP_PROMETHEUS_URL=http://localhost:9090


# Start Coroot
CMD ["coroot"]

Note: This basic Dockerfile uses the official Coroot image. For production deployments with ClickHouse and Prometheus integration, see the advanced configuration sections below.

Step 3: Advanced Dockerfile with ClickHouse

For a production-ready setup with ClickHouse for data storage:

FROM ghcr.io/coroot/coroot:latest


# Set working directory
WORKDIR /app


# Create data directories
RUN mkdir -p /data/clickhouse /data/coroot


# Expose Coroot web interface port
EXPOSE 8080


# Set environment variables
ENV BOOTSTRAP_CLICKHOUSE_ADDRESS=clickhouse:9000
ENV BOOTSTRAP_PROMETHEUS_URL=http://prometheus:9090
ENV DATA_DIR=/data/coroot


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD wget --quiet --tries=1 --spider http://localhost:8080/health || exit 1


# Start Coroot
CMD ["coroot", "--data-dir=/data/coroot"]

Step 4: Create Docker Compose Configuration for Local Testing

Create a docker-compose.yml file for local testing with ClickHouse:

version: '3.8'


services:
  clickhouse:
    image: clickhouse/clickhouse-server:latest
    ports:
      - "9000:9000"
      - "8123:8123"
    volumes:
      - clickhouse-data:/var/lib/clickhouse
    environment:
      CLICKHOUSE_DB: coroot
      CLICKHOUSE_USER: coroot
      CLICKHOUSE_PASSWORD: coroot_password
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "localhost:8123/ping"]
      interval: 30s
      timeout: 5s
      retries: 3


  coroot:
    build: .
    ports:
      - "8080:8080"
    depends_on:
      - clickhouse
    environment:
      BOOTSTRAP_CLICKHOUSE_ADDRESS: clickhouse:9000
      BOOTSTRAP_CLICKHOUSE_USER: coroot
      BOOTSTRAP_CLICKHOUSE_PASSWORD: coroot_password
      BOOTSTRAP_CLICKHOUSE_DATABASE: coroot
      BOOTSTRAP_PROMETHEUS_URL: http://prometheus:9090
    volumes:
      - coroot-data:/data/coroot


volumes:
  clickhouse-data:
  coroot-data:

Important Note: Klutch.sh does not support Docker Compose for deployment. This configuration is only for local development and testing. For production deployment on Klutch.sh, you’ll need to deploy ClickHouse and Coroot as separate applications.

Step 5: Create Environment Configuration

Create a .env.example file to document the required environment variables:

Terminal window
# Coroot Configuration
DATA_DIR=/data/coroot


# ClickHouse Configuration
BOOTSTRAP_CLICKHOUSE_ADDRESS=clickhouse-app.klutch.sh:8000
BOOTSTRAP_CLICKHOUSE_USER=coroot
BOOTSTRAP_CLICKHOUSE_PASSWORD=your-secure-password-here
BOOTSTRAP_CLICKHOUSE_DATABASE=coroot


# Prometheus Configuration
BOOTSTRAP_PROMETHEUS_URL=http://prometheus-app.klutch.sh:8000


# Optional: Additional Prometheus sources
BOOTSTRAP_PROMETHEUS_EXTRA_SELECTOR=cluster="production"


# Optional: Refresh intervals
BOOTSTRAP_REFRESH_INTERVAL=15s


# Optional: Disable ClickHouse for testing (uses in-memory storage)
DISABLE_CLICKHOUSE=false

Security Note: Never commit actual passwords or sensitive data to your repository. Use environment variables in Klutch.sh dashboard.

Step 6: Test Locally (Optional)

Before deploying to Klutch.sh, you can test your Coroot setup locally using Docker Compose:

Terminal window
# Start all services
docker-compose up -d


# View logs
docker-compose logs -f coroot


# Access Coroot at http://localhost:8080


# Stop all services
docker-compose down

For testing without ClickHouse, you can run Coroot standalone:

Terminal window
# Build the Docker image
docker build -t my-coroot .


# Run the container
docker run -d \
  --name coroot-test \
  -p 8080:8080 \
  -e DISABLE_CLICKHOUSE=true \
  -e BOOTSTRAP_PROMETHEUS_URL=http://your-prometheus:9090 \
  my-coroot


# View logs
docker logs -f coroot-test


# Access Coroot at http://localhost:8080


# Stop and remove the test container when done
docker stop coroot-test
docker rm coroot-test

Step 7: Create Documentation

Create a README.md file with setup instructions:

# Coroot Observability Platform


## Overview


This repository contains the Docker configuration for deploying Coroot on Klutch.sh.


## Features


- Zero instrumentation monitoring
- Automatic root cause analysis
- Service dependency mapping
- Cost optimization insights
- Integration with Prometheus and ClickHouse


## Deployment


See the full deployment guide in the Klutch.sh documentation.


## Configuration


Key environment variables:
- `BOOTSTRAP_CLICKHOUSE_ADDRESS`: ClickHouse server address
- `BOOTSTRAP_PROMETHEUS_URL`: Prometheus server URL
- `DATA_DIR`: Data directory for persistent storage


## Accessing Coroot


Once deployed, access your Coroot dashboard at:
https://example-app.klutch.sh

Step 8: Push to GitHub

Commit your Dockerfile and configuration files to your GitHub repository:

Terminal window
git add Dockerfile docker-compose.yml .env.example README.md
git commit -m "Add Coroot Dockerfile and configuration"
git remote add origin https://github.com/yourusername/coroot-klutch.git
git push -u origin main

Deploying to Klutch.sh

Now that your Coroot project is ready and pushed to GitHub, follow these steps to deploy it on Klutch.sh with persistent storage.

Deployment Steps

    1. Deploy ClickHouse First (Recommended)

      For production deployments, deploy ClickHouse as a separate application before deploying Coroot:

      • Create a new app in Klutch.sh for ClickHouse using the official ClickHouse Docker image
      • Configure it with TCP traffic type on the ClickHouse native protocol port
      • Set the internal port to 9000 (ClickHouse native protocol port)
      • Attach a persistent volume at /var/lib/clickhouse for data storage
      • Note the assigned URL (e.g., clickhouse-app.klutch.sh) for use in Coroot configuration

      Note: For TCP traffic on Klutch.sh, connections are made on port 8000, which routes to the internal port you specify.

    2. Log in to Klutch.sh

      Navigate to klutch.sh/app and sign in to your account.

    3. Create a New Project

      Go to Create Project and give your project a meaningful name (e.g., “Coroot Monitoring”).

    4. Create a New App

      Navigate to Create App and configure the following settings:

    5. Select Your Repository

      • Choose GitHub as your Git source
      • Select the repository containing your Dockerfile
      • Choose the branch you want to deploy (usually main or master)

    6. Configure Traffic Type

      • Traffic Type: Select HTTP (Coroot serves a web interface via HTTP)
      • Internal Port: Set to 8080 (the default port that Coroot listens on)

    7. Set Environment Variables

      Add the following environment variables for your Coroot configuration:

      Required Variables:

      • BOOTSTRAP_CLICKHOUSE_ADDRESS: Your ClickHouse server address (e.g., clickhouse-app.klutch.sh:8000)
      • BOOTSTRAP_CLICKHOUSE_USER: ClickHouse username (e.g., coroot)
      • BOOTSTRAP_CLICKHOUSE_PASSWORD: ClickHouse password (use a strong password)
      • BOOTSTRAP_CLICKHOUSE_DATABASE: Database name (e.g., coroot)
      • BOOTSTRAP_PROMETHEUS_URL: Your Prometheus server URL (e.g., http://prometheus-app.klutch.sh:8000)
      • DATA_DIR: Set to /data/coroot for persistent storage

      Optional Variables:

      • BOOTSTRAP_REFRESH_INTERVAL: Metrics refresh interval (default: 15s)
      • BOOTSTRAP_PROMETHEUS_EXTRA_SELECTOR: Additional Prometheus label selector

      For Testing Without ClickHouse:

      • DISABLE_CLICKHOUSE: Set to true to use in-memory storage (not recommended for production)

      Security Note: Always use strong, unique passwords for production deployments.

    8. Attach a Persistent Volume

      This is critical for ensuring your Coroot data persists across deployments and restarts:

      • In the Volumes section, click “Add Volume”
      • Mount Path: Enter /data/coroot (this is where Coroot stores its configuration and cache data)
      • Size: Choose an appropriate size based on your monitoring needs (e.g., 10GB for small deployments, 50GB+ for large infrastructures)

      Important: Coroot requires persistent storage to maintain configuration and cached data between container restarts.

    9. Configure Additional Settings

      • Region: Select the region closest to your infrastructure for optimal latency
      • Compute Resources: Choose CPU and memory based on your monitoring scale (minimum 1GB RAM recommended)
      • Instances: Start with 1 instance (Coroot is designed for single-instance operation)

    10. Deploy Your Application

      Click “Create” to start the deployment. Klutch.sh will:

      • Automatically detect your Dockerfile in the repository root
      • Build the Docker image
      • Attach the persistent volume
      • Start your Coroot container
      • Assign a URL for external access

    11. Access Your Coroot Dashboard

      Once deployment is complete, you’ll receive a URL like example-app.klutch.sh. Navigate to this URL in your browser to access your Coroot dashboard:

      https://example-app.klutch.sh

      On first access, Coroot will guide you through the initial setup process.

Configuring Data Sources

After your Coroot instance is deployed, you need to configure your data sources for monitoring:

Connecting Prometheus

  1. Log in to your Coroot dashboard at https://example-app.klutch.sh
  2. Navigate to Settings → Integrations
  3. Click “Add Prometheus”
  4. Enter your Prometheus URL (e.g., http://prometheus-app.klutch.sh:8000)
  5. (Optional) Add custom labels or filters
  6. Click “Save” to start collecting metrics

Configuring ClickHouse Storage

If you haven’t set ClickHouse configuration via environment variables:

  1. Go to Settings → Storage
  2. Enter your ClickHouse connection details:
    • Host: clickhouse-app.klutch.sh
    • Port: 8000 (external port on Klutch.sh)
    • Database: coroot
    • Username: Your ClickHouse username
    • Password: Your ClickHouse password
  3. Click “Test Connection” to verify
  4. Click “Save” to enable persistent storage

Adding Application Instrumentation

For enhanced monitoring with traces and detailed metrics:

# Add Coroot node agent to your Kubernetes cluster (if applicable)
apiVersion: v1
kind: DaemonSet
metadata:
  name: coroot-node-agent
spec:
  template:
    spec:
      containers:
      - name: coroot-node-agent
        image: ghcr.io/coroot/coroot-node-agent:latest
        env:
        - name: COROOT_URL
          value: "https://example-app.klutch.sh"

Note: The above configuration is for reference when monitoring external Kubernetes clusters. Adapt based on your infrastructure.

Environment Variables Reference

Complete list of Coroot environment variables you can configure in Klutch.sh:

VariableDescriptionRequiredDefault
DATA_DIRDirectory for Coroot data storageNo/data
BOOTSTRAP_CLICKHOUSE_ADDRESSClickHouse server addressYes*None
BOOTSTRAP_CLICKHOUSE_USERClickHouse usernameYes*default
BOOTSTRAP_CLICKHOUSE_PASSWORDClickHouse passwordYes*None
BOOTSTRAP_CLICKHOUSE_DATABASEClickHouse database nameYes*coroot
BOOTSTRAP_PROMETHEUS_URLPrometheus server URLYesNone
BOOTSTRAP_PROMETHEUS_EXTRA_SELECTORAdditional Prometheus label filtersNoNone
BOOTSTRAP_REFRESH_INTERVALMetrics refresh intervalNo15s
DISABLE_CLICKHOUSEDisable ClickHouse (use in-memory storage)Nofalse
LOG_LEVELLogging level (debug, info, warn, error)Noinfo

*Required unless DISABLE_CLICKHOUSE=true

Deploying ClickHouse on Klutch.sh

For production deployments, deploy ClickHouse as a separate application:

ClickHouse Dockerfile

Create a separate repository for ClickHouse with this Dockerfile:

FROM clickhouse/clickhouse-server:latest


# Create data directory
RUN mkdir -p /var/lib/clickhouse


# Expose native protocol port
EXPOSE 9000


# Expose HTTP interface port (optional)
EXPOSE 8123


# Set default user and database
ENV CLICKHOUSE_DB=coroot
ENV CLICKHOUSE_USER=coroot
ENV CLICKHOUSE_PASSWORD=changeme


# Start ClickHouse
CMD ["/entrypoint.sh"]

Deploy ClickHouse on Klutch.sh

    1. Push your ClickHouse Dockerfile to a GitHub repository

    2. Create a new app in Klutch.sh for ClickHouse

    3. Configure traffic settings:

      • Traffic Type: Select TCP (ClickHouse uses TCP for native protocol)
      • Internal Port: Set to 9000 (ClickHouse native protocol port)

    4. Set environment variables:

      • CLICKHOUSE_DB: coroot
      • CLICKHOUSE_USER: coroot
      • CLICKHOUSE_PASSWORD: A strong password

    5. Attach a persistent volume:

      • Mount Path: /var/lib/clickhouse
      • Size: 20GB or more depending on your monitoring scale

    6. Deploy and note the assigned URL (e.g., clickhouse-app.klutch.sh)

    7. Use clickhouse-app.klutch.sh:8000 as your BOOTSTRAP_CLICKHOUSE_ADDRESS in Coroot

Important: When using TCP traffic on Klutch.sh, connect to port 8000, which routes to your configured internal port.

Monitoring Your Infrastructure

Setting Up Monitors

Coroot automatically creates monitors for your services. To customize:

  1. Navigate to Applications in the Coroot dashboard
  2. Select an application to monitor
  3. Click “Configure Monitors”
  4. Enable or disable specific checks (CPU, memory, latency, errors, etc.)
  5. Set custom thresholds for alerts
  6. Configure notification channels

Creating Custom Dashboards

  1. Go to Dashboards → New Dashboard
  2. Add widgets for metrics you want to track
  3. Customize visualizations (graphs, tables, heatmaps)
  4. Save and share with your team

Service Map

View your service dependencies:

  1. Click on Service Map in the main navigation
  2. Explore connections between your services
  3. Click on any service to see detailed metrics
  4. Identify bottlenecks and performance issues

Production Best Practices

Security Recommendations

  • Strong Passwords: Use a password manager to generate strong, random passwords for ClickHouse and any authentication
  • Environment Variables: Store all sensitive credentials as environment variables in Klutch.sh, never in your Dockerfile
  • HTTPS Only: Klutch.sh provides HTTPS by default; ensure you access Coroot only via HTTPS
  • Regular Backups: Implement a backup strategy for your ClickHouse data using volume snapshots
  • Update Regularly: Keep Coroot and ClickHouse updated to the latest versions for security patches
  • Network Security: Use private networking between Coroot and ClickHouse when possible
  • Access Control: Implement authentication and role-based access control for the Coroot dashboard

Performance Optimization

  • ClickHouse Tuning: Configure ClickHouse memory and CPU limits based on your data volume
  • Data Retention: Configure retention policies in ClickHouse to manage storage costs
  • Query Optimization: Use Coroot’s built-in query optimization features
  • Resource Allocation: Monitor Coroot’s resource usage and scale accordingly
  • Caching: Coroot includes intelligent caching; ensure it’s properly configured

Monitoring and Maintenance

Monitor your Coroot deployment for:

  • Response Times: Ensure the dashboard loads quickly
  • ClickHouse Performance: Watch query execution times and storage usage
  • Memory Usage: Monitor memory consumption for both Coroot and ClickHouse
  • Data Ingestion: Track metrics ingestion rate and any gaps
  • Alert Delivery: Verify alerts are being delivered promptly

Data Management

  • Regular Backups: Create regular backups of your ClickHouse volume
  • Data Retention: Configure automatic data cleanup in ClickHouse
  • Monitoring Coverage: Regularly audit which services are being monitored
  • Dashboard Maintenance: Keep dashboards up-to-date as your infrastructure evolves

Integrating with External Services

Prometheus Configuration

To send metrics from Prometheus to Coroot:

# Add to your prometheus.yml
remote_write:
  - url: https://example-app.klutch.sh/api/v1/write
    basic_auth:
      username: your-username
      password: your-password

Alerting Integration

Configure alert destinations in Coroot:

  1. Go to Settings → Notifications
  2. Add notification channels:
    • Slack: Webhook URL for Slack notifications
    • Email: SMTP configuration for email alerts
    • PagerDuty: Integration key for incident management
    • Webhook: Custom webhook for other services

Grafana Integration

Export Coroot data to Grafana:

  1. In Coroot, go to Settings → Integrations
  2. Enable Grafana data source
  3. Copy the data source URL
  4. In Grafana, add a new Prometheus data source
  5. Use the Coroot URL as the data source endpoint

Troubleshooting

Cannot Access Coroot Dashboard

  • Verify your app is running in the Klutch.sh dashboard
  • Check that the internal port is set to 8080
  • Ensure HTTP traffic type is selected
  • Review application logs for startup errors
  • Verify network connectivity to ClickHouse and Prometheus

ClickHouse Connection Errors

  • Verify ClickHouse is deployed and running
  • Check the BOOTSTRAP_CLICKHOUSE_ADDRESS format (should include port 8000)
  • Ensure credentials are correct
  • Test connectivity using ClickHouse client tools
  • Verify the persistent volume is attached at /var/lib/clickhouse

No Metrics Showing

  • Verify Prometheus URL is correct and accessible
  • Check that Prometheus is exposing metrics
  • Review Coroot logs for metric ingestion errors
  • Ensure there’s no firewall blocking connections
  • Verify Prometheus remote_write configuration if applicable

Data Not Persisting

  • Confirm the persistent volume is attached at /data/coroot
  • Check the volume has sufficient space
  • Verify ClickHouse volume is properly mounted
  • Review file permissions on mounted volumes

Performance Issues

  • Monitor CPU and memory usage in Klutch.sh dashboard
  • Consider increasing compute resources
  • Check ClickHouse query performance
  • Review data retention policies
  • Optimize metric cardinality in Prometheus

High Memory Usage

  • Check the number of time series being monitored
  • Review ClickHouse memory configuration
  • Implement data retention policies
  • Consider scaling ClickHouse resources
  • Optimize Prometheus metric labels

Upgrading Coroot

To upgrade Coroot to a new version:

  1. Update the image version in your Dockerfile:

    FROM ghcr.io/coroot/coroot:v1.5.0

  2. Commit and push the changes to GitHub:

    Terminal window
    git add Dockerfile
    git commit -m "Upgrade Coroot to version 1.5.0"
    git push

  3. Klutch.sh will automatically rebuild and redeploy your application

  4. Your data and configuration will be preserved because they’re stored in persistent volumes

  5. Review the Coroot changelog for any breaking changes or new features

Advanced Configuration

High Availability Setup

For production environments requiring high availability:

  1. Deploy multiple ClickHouse replicas with replication
  2. Use a load balancer for ClickHouse connections
  3. Configure Coroot with multiple Prometheus sources
  4. Implement automated backups and disaster recovery procedures

Multi-Tenant Configuration

To monitor multiple environments:

  1. Deploy separate Coroot instances for each environment
  2. Use Prometheus federation to aggregate metrics
  3. Configure different retention policies per environment
  4. Implement role-based access control

Custom Metrics and Checks

Add custom application metrics:

# Example Prometheus metric
my_app_requests_total{status="200"} 1000
my_app_latency_seconds{quantile="0.99"} 0.5

Coroot will automatically detect and visualize these metrics.

Cost Optimization

Reducing Storage Costs

  • Configure aggressive data retention policies in ClickHouse
  • Use ClickHouse compression settings
  • Archive old data to object storage
  • Monitor and optimize metric cardinality

Compute Optimization

  • Right-size your Coroot and ClickHouse instances
  • Use auto-scaling where appropriate
  • Schedule intensive queries during off-peak hours
  • Implement query result caching

Additional Resources

Conclusion

Deploying Coroot to Klutch.sh with Docker provides a powerful, self-hosted observability solution with persistent storage and seamless integration with your existing monitoring infrastructure. By following this guide, you’ve set up a production-ready Coroot instance with proper data persistence, ClickHouse backend, and comprehensive monitoring capabilities. Your observability platform is now ready to provide deep insights into your applications and infrastructure, enabling you to quickly identify and resolve issues while optimizing performance and costs.