Skip to main content
Skip to main content
Edit this page

All in one

This comprehensive Docker image bundles all ClickStack Open Source components:

  • ClickHouse
  • HyperDX
  • OpenTelemetry (OTel) collector (exposing OTLP on ports 4317 and 4318)
  • MongoDB (for persistent application state)

This option includes authentication, enabling the persistence of dashboards, alerts, and saved searches across sessions and users.

Suitable for​

  • Demos
  • Local testing of the full stack

Deployment steps​


Deploy with Docker​

The following will run an OpenTelemetry collector (on port 4317 and 4318) and the HyperDX UI (on port 8080).

docker run -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-all-in-one:latest
Image Name Update

ClickStack images are now published as clickhouse/clickstack-* (previously docker.hyperdx.io/hyperdx/*).

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 integrated ClickHouse instance.

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

Ingest data​

To ingest data see "Ingesting data".

Persisting data and settings​

To persist data and settings across restarts of the container, you can modify the above docker command to mount the paths /data/db, /var/lib/clickhouse and /var/log/clickhouse-server. For example:

# ensure directories exist
mkdir -p .volumes/db .volumes/ch_data .volumes/ch_logs
# modify command to mount paths
docker run \
  -p 8080:8080 \
  -p 4317:4317 \
  -p 4318:4318 \
  -v "$(pwd)/.volumes/db:/data/db" \
  -v "$(pwd)/.volumes/ch_data:/var/lib/clickhouse" \
  -v "$(pwd)/.volumes/ch_logs:/var/log/clickhouse-server" \
  clickhouse/clickstack-all-in-one:latest

Deploying to production​

This option shouldn't be deployed to production for the following reasons:

  • Non-persistent storage: All data is stored using the Docker native overlay filesystem. This setup doesn't support performance at scale, and data will be lost if the container is removed or restarted - unless users mount the required file paths.
  • Lack of component isolation: All components run within a single Docker container. This prevents independent scaling and monitoring and applies any cgroup limits globally to all processes. As a result, components may compete for CPU and memory.

Customizing ports​

If you need to customize the application (8080) or API (8000) ports that HyperDX Local runs on, you'll need to modify the docker run command to forward the appropriate ports and set a few environment variables.

Customizing the OpenTelemetry ports can simply be changed by modifying the port forwarding flags. For example, replacing -p 4318:4318 with -p 4999:4318 to change the OpenTelemetry HTTP port to 4999.

docker run -p 8080:8080 -p 4317:4317 -p 4999:4318 clickhouse/clickstack-all-in-one:latest

Using ClickHouse Cloud​

This distribution can be used with ClickHouse Cloud. While the local ClickHouse instance will still be deployed (and ignored), the OTel collector can be configured to use a ClickHouse Cloud instance by setting the environment variables CLICKHOUSE_ENDPOINT, CLICKHOUSE_USER and CLICKHOUSE_PASSWORD.

For example:

export CLICKHOUSE_ENDPOINT=<HTTPS ENDPOINT>
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

docker run -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} -e CLICKHOUSE_USER=default -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-all-in-one:latest

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, navigate to Team Settings and create a connection to your ClickHouse Cloud service - followed by the required sources.

Configuring the OpenTelemetry collector​

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

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.