Getting started with open source ClickStack

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/use-cases/observability/clickstack/getting-started/oss.md)

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.

Tip

A managed version of ClickStack is also available — see [Managed ClickStack](/docs/use-cases/observability/clickstack/getting-started/managed).

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

## Deploy the stack with docker[​](#deploy-stack-with-docker "Direct link to 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 (8123).

```
docker run --name clickstack -p 8123:8123 -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-all-in-one:latest clickstack
```

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 \
  --name clickstack \
  -p 8123:8123 \
  -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
```

Navigate to the ClickStack UI

## Navigate to the ClickStack UI[​](#navigate-to-hyperdx-ui "Direct link to Navigate to the ClickStack UI")

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

## Explore the product[​](#explore-the-product "Direct link to Explore the product")

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

To continue using the local cluster:

- [Example dataset](/docs/use-cases/observability/clickstack/getting-started/sample-data) - Load an example dataset from our public demo. Diagnose a simple issue.
- [Local files and metrics](/docs/use-cases/observability/clickstack/getting-started/local-data) - 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:

- [Remote demo dataset](/docs/use-cases/observability/clickstack/getting-started/remote-demo-data) - Explore a demo dataset in our demo ClickHouse service.

## Alternative deployment models[​](#alternative-deployment-models "Direct link to Alternative deployment models")

### Local mode[​](#local-mode "Direct link to Local mode")

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

**Authentication isn't supported**.

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

For further details on this deployment model, see ["Local Mode Only"](/docs/use-cases/observability/clickstack/deployment/local-mode-only).

### Hosted version[​](#hosted-version "Direct link to Hosted version")

You can use a hosted version of ClickStack in local mode available at [play-clickstack.clickhouse.com](https://play-clickstack.clickstack.com).

### Self-hosted version[​](#self-hosted-version "Direct link to Self-hosted version")

Run with docker

### Run with docker[​](#run-local-with-docker "Direct link to 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 prompted to create a user as **local mode does not include authentication**.

Complete connection credentials

### Complete connection credentials[​](#complete-connection-credentials "Direct link to 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](/docs/use-cases/observability/clickstack/getting-started/remote-demo-data).

- [Deploy the stack with docker](#deploy-stack-with-docker)- [Navigate to the ClickStack UI](#navigate-to-hyperdx-ui)- [Explore the product](#explore-the-product)- [Alternative deployment models](#alternative-deployment-models)
        - [Local mode](#local-mode)- [Hosted version](#hosted-version)- [Self-hosted version](#self-hosted-version)- [Run with docker](#run-local-with-docker)- [Complete connection credentials](#complete-connection-credentials)

Was this page helpful?