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 thehealth_check
extension24225
: Fluentd receiver for log ingestion4317
: 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
:
Navigate to the HyperDX UI
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.
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 asdepends_on
are removed. -
Modify the OTel collector to use a ClickHouse Cloud instance by setting the environment variables
CLICKHOUSE_ENDPOINT
,CLICKHOUSE_USER
andCLICKHOUSE_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 port8443
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.