Embedded in ClickHouse

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

ClickStack is bundled directly into the ClickHouse server binary. This means you can access the ClickStack UI (HyperDX) from your ClickHouse instance without deploying any additional components. This deployment is similar to the public demo at [play-clickstack.clickhouse.com](https://play-clickstack.clickhouse.com), but running against your own ClickHouse instance and data.

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

- Trying ClickStack with minimal setup
- Exploring your own ClickHouse data with an observability UI
- Demos and evaluations

### Limitations[​](#limitations "Direct link to Limitations")

This embedded version is **not designed for production use**. The following features are not available compared to the [production-ready OSS deployments](/docs/use-cases/observability/clickstack/deployment/oss):

- [Alerting](/docs/use-cases/observability/clickstack/alerts)
- [Dashboard](/docs/use-cases/observability/clickstack/dashboards) and [search](/docs/use-cases/observability/clickstack/search) persistence — dashboards and saved searches are not retained across sessions
- Customizable query settings
- [Event patterns](/docs/use-cases/observability/clickstack/event_patterns)

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

- Docker- Binary

Start ClickHouse

### Start ClickHouse[​](#start-clickhouse-docker "Direct link to Start ClickHouse")

Pull and run the ClickHouse server image with a password set:

```
docker run --rm -it -p 8123:8123 -e CLICKHOUSE_PASSWORD=password clickhouse/clickhouse-server:head-alpine
```

Running without a password

If you prefer to run without a password, you must explicitly enable default access management:

```
docker run --rm -it -p 8123:8123 -e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 clickhouse/clickhouse-server:head-alpine
```

Open the ClickStack UI

### Open the ClickStack UI[​](#open-clickstack-ui-docker "Direct link to Open the ClickStack UI")

Open <http://localhost:8123> in your browser and click **ClickStack**.

Enter the username `default` and the password `password` to connect to the local instance.

Create a source

### Create a source[​](#create-a-source-docker "Direct link to Create a source")

If you have existing OpenTelemetry tables, ClickStack will detect them and create sources automatically.

On a fresh installation, you will be prompted to create a source. Complete the **Table** field with the appropriate table name (e.g. `otel_logs`) and click **Save New Source**.

If you don't have data yet, see [Ingesting data](/docs/use-cases/observability/clickstack/ingesting-data) for available options.

Start ClickHouse

### Start ClickHouse[​](#start-clickhouse-binary "Direct link to Start ClickHouse")

Download and start ClickHouse:

```
curl https://clickhouse.com/ | sh
```

Optional: Enable system log tables

To explore ClickHouse's own internal logs and metrics, create a configuration snippet in your working directory before starting the server:

```
mkdir -p config.d && cat > config.d/query_logs.xml << 'EOF'
<clickhouse>
    <query_log>
        <database>system</database>
        <table>query_log</table>
    </query_log>
    <query_thread_log>
        <database>system</database>
        <table>query_thread_log</table>
    </query_thread_log>
    <query_views_log>
        <database>system</database>
        <table>query_views_log</table>
    </query_views_log>
    <metric_log>
        <database>system</database>
        <table>metric_log</table>
    </metric_log>
    <asynchronous_metric_log>
        <database>system</database>
        <table>asynchronous_metric_log</table>
    </asynchronous_metric_log>
</clickhouse>
EOF
```

With this enabled, you can create a **Log Source** pointing to `system.query_log` after opening ClickStack:

|  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Setting Value|  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | **Name** `Query Logs`| **Database** `system`| **Table** `query_log`| **Timestamp Column** `event_time`| **Default Select** `event_time, query_kind, query, databases, tables, initial_user, projections, memory_usage, written_rows, read_rows, query_duration_ms` | | | | | | | | | | | |

Start the server:

```
./clickhouse server
```

Open the ClickStack UI

### Open the ClickStack UI[​](#open-clickstack-ui-binary "Direct link to Open the ClickStack UI")

Open <http://localhost:8123> in your browser and click **ClickStack**. A connection to the local instance is created automatically.

Create a source

### Create a source[​](#create-a-source-binary "Direct link to Create a source")

If you have existing OpenTelemetry tables, ClickStack will detect them and create sources automatically.

If you don't have data yet, see [Ingesting data](/docs/use-cases/observability/clickstack/ingesting-data) for available options.

## Next steps[​](#next-steps "Direct link to Next steps")

If you're ready to move beyond evaluation, consider a production-ready deployment:

- [All-in-One](/docs/use-cases/observability/clickstack/deployment/all-in-one) — single container with all components, including persistence and authentication
- [Docker Compose](/docs/use-cases/observability/clickstack/deployment/docker-compose) — individual components for more control
- [Helm](/docs/use-cases/observability/clickstack/deployment/helm) — recommended for production Kubernetes deployments
- [Managed ClickStack](/docs/use-cases/observability/clickstack/getting-started/managed) — fully managed on ClickHouse Cloud

- [Suitable for](#suitable-for)- [Limitations](#limitations)- [Deployment steps](#deployment-steps)
      - [Start ClickHouse](#start-clickhouse-docker)- [Open the ClickStack UI](#open-clickstack-ui-docker)- [Create a source](#create-a-source-docker)- [Start ClickHouse](#start-clickhouse-binary)- [Open the ClickStack UI](#open-clickstack-ui-binary)- [Create a source](#create-a-source-binary)- [Next steps](#next-steps)

Was this page helpful?