Skip to main content
Skip to main content
Edit this page

Getting Started with ClickStack

Getting started with ClickStack is straightforward thanks to the availability of prebuilt Docker images. These images are based on the official ClickHouse Debian package and are available in multiple distributions to suit different use cases.

Local deployment​

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 stack with docker​

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

Persisting data and settings

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

For example:

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

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:

Deploy with ClickHouse Cloud​

Users can deploy ClickStack against ClickHouse Cloud, benefiting from a fully managed, secure backend while retaining complete control over ingestion, schema, and observability workflows.

Create a ClickHouse Cloud service​

Follow the getting started guide for ClickHouse Cloud to create a service.

Copy connection details​

To find the connection details for HyperDX, navigate to the ClickHouse Cloud console and click the Connect button on the sidebar.

Copy the HTTP connection details, specifically the HTTPS endpoint (endpoint) and password.

Deploying to production

While we will use the default user to connect HyperDX, we recommend creating a dedicated user when going to production.

Deploy with docker​

Open a terminal and export the credentials copied above:

Run the following docker command:

This will expose an OpenTelemetry collector (on port 4317 and 4318), and the HyperDX UI (on port 8080).

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

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

Create a ClickHouse Cloud connection​

Navigate to Team Settings and click Edit for the Local Connection:

Rename the connection to Cloud and complete the subsequent form with your ClickHouse Cloud service credentials before clicking Save:

Explore the product​

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

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

Local mode​

Local mode is a way to deploy HyperDX without a database or OTel collector. You can connect directly to a ClickHouse server from your browser directly, with configuration stored locally in your browser's local or session storage. This image only includes the HyperDX UI.

Authentication is not supported.

This mode is intended to be used for quick testing, development, demos and debugging use cases where deploying a full HyperDX instance is not necessary.

Hosted Version​

You can use a hosted version of HyperDX in local mode available at play.hyperdx.io.

Self-Hosted Version​

Run with docker​

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

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, users can explore the dataset with the demo dataset instructions.