Skip to main content
Skip to main content
Edit this page

Docker Compose

All ClickStack 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 is not 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 HyperDX repo, change into the directory and run 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 the Helm chart.

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 "Create a ClickHouse Cloud connection".

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​

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

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. Users should:

  • Remove the ClickHouse service from the docker-compose.yaml 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:

    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.

JSON type support​

Beta feature. Learn more.

ClickStack has beta support for the JSON type from version 2.0.4.

For the benefits of this type see Benefits of the JSON type.

In order to enable support for the JSON type users must set the following environment variables:

  • OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' - enables support in the OTel collector, ensuring schemas are created using the JSON type.
  • BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true - enables support in the HyperDX application, allowing JSON data to be queried.

To set these, modify the relevant services in the docker-compose.yaml: