HyperDX Only

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

This option is designed if you already have a running ClickHouse instance populated with observability or event data.

HyperDX can be used independently of the rest of the stack and is compatible with any data schema - not just OpenTelemetry (OTel). This makes it suitable for custom observability pipelines already built on ClickHouse.

To enable full functionality, you must provide a MongoDB instance for storing application state, including dashboards, saved searches, user settings, and alerts.

In this mode, data ingestion is left entirely to the user. You can ingest data into ClickHouse using your own hosted OpenTelemetry collector, direct ingestion from client libraries, ClickHouse-native table engines (such as Kafka or S3), ETL pipelines, or managed ingestion services like ClickPipes. This approach offers maximum flexibility and is suitable for teams that already operate ClickHouse and want to layer HyperDX on top for visualization, search, and alerting.

### Suitable for[​](#suitable-for "Direct link to Suitable for")

- Existing ClickHouse users
- Custom event pipelines

## Deployment steps[​](#deployment-steps "Direct link to Deployment steps")

  

Deploy with Docker

### Deploy with Docker[​](#deploy-hyperdx-with-docker "Direct link to Deploy with Docker")

Run the following command, modifying `YOUR_MONGODB_URI` as required.

```
docker run -e MONGO_URI=mongodb://YOUR_MONGODB_URI -p 8080:8080 docker.hyperdx.io/hyperdx/hyperdx
```

Navigate to the HyperDX UI

### Navigate to the HyperDX UI[​](#navigate-to-hyperdx-ui "Direct link to 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` you'll be prompted for connection details.

Complete connection details

### Complete connection details[​](#complete-connection-details "Direct link to Complete connection details")

Connect to your own external ClickHouse cluster e.g. ClickHouse Cloud.

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`.

Creating a source

Creating a source requires tables to exist in ClickHouse. If you don't have data, we recommend deploying the ClickStack OpenTelemetry collector to create tables.

## Using Docker Compose[​](#using-docker-compose "Direct link to Using Docker Compose")

You can modify the [Docker Compose configuration](/docs/use-cases/observability/clickstack/deployment/docker-compose) to achieve the same effect as this guide, removing the OTel collector and ClickHouse instance from the manifest.

## ClickStack OpenTelemetry collector[​](#otel-collector "Direct link to ClickStack OpenTelemetry collector")

Even if you're managing your own OpenTelemetry collector, independent of the other components in the stack, we still recommend using the ClickStack distribution of the collector. This ensures the default schema is used and best practices for ingestion are applied.

For details on deploying and configuring a standalone collector see ["Ingesting with OpenTelemetry"](/docs/use-cases/observability/clickstack/ingesting-data/otel-collector#modifying-otel-collector-configuration).

## JSON type support[​](#json-type-support "Direct link to JSON type support")

Beta feature. [Learn more.](/docs/beta-and-experimental-features#beta-features)

Beta Feature - not production ready

JSON type support in **ClickStack** is a **beta feature**. While the JSON type itself is production-ready in ClickHouse 25.3+, its integration within ClickStack is still under active development and may have limitations, change in the future, or contain bugs.

ClickStack has beta support for the [JSON type](/docs/interfaces/formats/JSON) from version `2.0.4`.

For the benefits of this type see [Benefits of the JSON type](/docs/use-cases/observability/clickstack/ingesting-data/otel-collector#benefits-json-type).

In order to enable support for the JSON type you must set the following environment variables:

- `OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json'` - enables support in the OTel collector, ensuring schemas are created using the JSON type.
- `BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true` (ClickStack Open Source only) - enables support in the ClickStack UI application, allowing JSON data to be queried.

For the HyperDX-only image, users only need to set the `BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true` parameter e.g.

```
docker run -e BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true -e MONGO_URI=mongodb://YOUR_MONGODB_URI -p 8080:8080 docker.hyperdx.io/hyperdx/hyperdx
```

- [Suitable for](#suitable-for)- [Deployment steps](#deployment-steps)
    - [Deploy with Docker](#deploy-hyperdx-with-docker)- [Navigate to the HyperDX UI](#navigate-to-hyperdx-ui)- [Complete connection details](#complete-connection-details)- [Using Docker Compose](#using-docker-compose)- [ClickStack OpenTelemetry collector](#otel-collector)- [JSON type support](#json-type-support)

Was this page helpful?