Skip to main content
Skip to main content
Edit this page

Getting Started with Open Source ClickStack

To deploy ClickStack Open Source, where you run and manage ClickHouse and the ClickStack UI yourself, we provide prebuilt Docker images that bundle the UI, an OpenTelemetry collector, and ClickHouse into a single container - making local development, testing, and self-managed deployments straightforward to get started.

These images are based on the official ClickHouse Debian package and are available in multiple distributions to suit different use cases.

The simplest option is a single-image distribution that includes all core components of the stack bundled together:

  • HyperDX UI
  • OpenTelemetry (OTel) collector
  • ClickHouse

This all-in-one image allows you to launch the full stack with a single command, making it ideal for testing, experimentation, or quick local deployments.

Deploy the stack with docker​

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

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/*).

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:

# 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

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

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

HyperDX will automatically connect to the local cluster and create data sources for the logs, traces, metrics, and sessions - allowing you to explore the product immediately.

Explore the product​

With the stack deployed, try one of our same datasets.

To continue using the local cluster:

  • Example dataset - Load an example dataset from our public demo. Diagnose a simple issue.
  • Local files and metrics - Load local files and monitor system on OSX or Linux using a local OTel collector.

Alternatively, you can connect to a demo cluster where you can explore a larger dataset:

Alternative deployment models​

Local mode​

Local mode is a way to deploy HyperDX without needing to authenticate.

Authentication is not supported.

This mode is intended to be used for quick testing, development, demos and debugging use cases where authentication and settings persistence is not necessary.

For further details on this deployment model, see "Local Mode Only".

Hosted version​

You can use a hosted version of ClickStack in local mode available at play-clickstack.clickhouse.com.

Self-hosted version​

Run with docker​

The self-hosted local mode image comes with an OpenTelemetry collector, the ClickStack UI and a ClickHouse server pre-configured as well. This makes it easy to consume telemetry data from your applications and visualize it with minimal external setup. To get started with the self-hosted version, simply run the Docker container with the appropriate ports forwarded:

docker run -p 8080:8080 clickhouse/clickstack-local:latest

Unlike the "All in one" image, you will not be promoted to create a user as local mode does not include authentication.

Complete connection credentials​

To connect to your own external ClickHouse cluster, you can manually enter your connection credentials.

Alternatively, for a quick exploration of the product, you can also click Connect to Demo Server to access preloaded datasets and try ClickStack with no setup required.

If connecting to the demo server, you can explore the dataset with the demo dataset instructions.