Skip to main content
Skip to main content
Edit this page

Docker Compose

All ClickStack Open Source components are distributed separately as individual Docker images:

  • ClickHouse
  • HyperDX
  • OpenTelemetry (OTel) collector
  • MongoDB

These images can be combined and deployed locally using Docker Compose.

Docker Compose exposes additional ports for observability and ingestion based on the default otel-collector setup:

  • 13133: Health check endpoint for the health_check extension
  • 24225: Fluentd receiver for log ingestion
  • 4317: OTLP gRPC receiver (standard for traces, logs, and metrics)
  • 4318: OTLP HTTP receiver (alternative to gRPC)
  • 8888: Prometheus metrics endpoint for monitoring the collector itself

These ports enable integrations with a variety of telemetry sources and make the OpenTelemetry collector production-ready for diverse ingestion needs.

Suitable for​

  • Local testing
  • Proof of concepts
  • Production deployments where fault tolerance isn't required and a single server is sufficient to host all ClickHouse data
  • When deploying ClickStack but hosting ClickHouse separately e.g. using ClickHouse Cloud.

Deployment steps​


Clone the repo​

To deploy with Docker Compose clone the ClickStack repo, change into the directory and run docker-compose up:

git clone https://github.com/ClickHouse/ClickStack.git
docker compose up

Visit http://localhost:8080 to access the HyperDX UI.

Create a user, providing a username and password which meets the requirements.

On clicking Create data sources will be created for the ClickHouse instance deployed with Docker Compose.

Overriding default connection

You can override the default connection to the integrated ClickHouse instance. For details, see "Using ClickHouse Cloud".

For an example of using an alternative ClickHouse instance, see "Using ClickHouse Cloud".

Complete connection details​

To connect to the deployed ClickHouse instance, simply click Create and accept the default settings.

If you prefer to connect to your own external ClickHouse cluster e.g. ClickHouse Cloud, you can manually enter your connection credentials.

If prompted to create a source, retain all default values and complete the Table field with the value otel_logs. All other settings should be auto-detected, allowing you to click Save New Source.

Modifying compose settings​

You can modify settings for the stack, such as the version used, through the environment variable file:

user@example-host clickstack % cat .env

# Used by docker-compose.yml
IMAGE_NAME_DOCKERHUB=clickhouse/clickstack-all-in-one
LOCAL_IMAGE_NAME_DOCKERHUB=clickhouse/clickstack-local
ALL_IN_ONE_IMAGE_NAME_DOCKERHUB=clickhouse/clickstack-all-in-one
OTEL_COLLECTOR_IMAGE_NAME_DOCKERHUB=clickhouse/clickstack-otel-collector
CODE_VERSION=2.8.0
IMAGE_VERSION_SUB_TAG=.8.0
IMAGE_VERSION=2
IMAGE_NIGHTLY_TAG=2-nightly
IMAGE_LATEST_TAG=latest

# Set up domain URLs
HYPERDX_API_PORT=8000 #optional (should not be taken by other services)
HYPERDX_APP_PORT=8080
HYPERDX_APP_URL=http://localhost
HYPERDX_LOG_LEVEL=debug
HYPERDX_OPAMP_PORT=4320

# Otel/Clickhouse config
HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE=default

Configuring the OpenTelemetry collector​

The OTel collector configuration can be modified if required - see "Modifying configuration".

Using ClickHouse Cloud​

This distribution can be used with ClickHouse Cloud, but it differs from Managed ClickStack. In this setup, you manage the ClickStack UI yourself while using ClickHouse Cloud only for compute and storage. Unless you have a specific reason to operate the UI independently, we recommend using Managed ClickStack, which includes integrated authentication and additional enterprise features, and removes the need to manage the ClickStack UI yourself.

You should:

  • Remove the ClickHouse service from the docker-compose.yml file. This is optional if testing, as the deployed ClickHouse instance will simply be ignored - although waste local resources. If removing the service, ensure any references to the service such as depends_on are removed.

  • Modify the OTel collector to use a ClickHouse Cloud instance by setting the environment variables CLICKHOUSE_ENDPOINT, CLICKHOUSE_USER and CLICKHOUSE_PASSWORD in the compose file. Specifically, add the environment variables to the OTel collector service:

    otel-collector:
    image: ${OTEL_COLLECTOR_IMAGE_NAME_DOCKERHUB}:${IMAGE_VERSION}
    environment:
      CLICKHOUSE_ENDPOINT: '<CLICKHOUSE_ENDPOINT>' # https endpoint here
      CLICKHOUSE_USER: '<CLICKHOUSE_USER>'
      CLICKHOUSE_PASSWORD: '<CLICKHOUSE_PASSWORD>'
      HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE: ${HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE}
      HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
      OPAMP_SERVER_URL: 'http://app:${HYPERDX_OPAMP_PORT}'
    ports:
      - '13133:13133' # health_check extension
      - '24225:24225' # fluentd receiver
      - '4317:4317' # OTLP gRPC receiver
      - '4318:4318' # OTLP http receiver
      - '8888:8888' # metrics extension
    restart: always
    networks:
      - internal

    The CLICKHOUSE_ENDPOINT should be the ClickHouse Cloud HTTPS endpoint, including the port 8443 e.g. https://mxl4k3ul6a.us-east-2.aws.clickhouse.com:8443

  • On connecting to the HyperDX UI and creating a connection to ClickHouse, use your Cloud credentials.

Schema choice: Map vs JSON​

ClickStack stores attributes as Map(LowCardinality(String), String) columns by default. This is the recommended schema for observability workloads. Combined with bucketed map serialization and text indexes on map keys and values, it provides selective lookups without the per-key ingest overhead of dynamic JSON subcolumns.

A JSON-typed schema is available in beta for evaluation on workloads with a small, stable attribute key-set. It is not recommended as the default. See Map vs JSON type for the full comparison and the env vars required to enable JSON support.