> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedded in ClickHouse

> Using ClickStack embedded in ClickHouse Server - The ClickHouse Observability Stack

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

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.

<h3 id="suitable-for">
  Suitable for
</h3>

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

<h3 id="limitations">
  Limitations
</h3>

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

* [Alerting](/clickstack/features/alerts)
* [Dashboard](/clickstack/features/dashboards/overview) and [search](/clickstack/features/search) persistence — dashboards and saved searches are not retained across sessions
* Customizable query settings
* [Event patterns](/clickstack/features/event-patterns)

<h2 id="deployment-steps">
  Deployment steps
</h2>

<Tabs>
  <Tab title="Docker">
    <Steps>
      <Step>
        <h3 id="start-clickhouse-docker">
          Start ClickHouse
        </h3>

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

        ```shell theme={null}
        docker run --rm -it -p 8123:8123 -e CLICKHOUSE_PASSWORD=password clickhouse/clickhouse-server:head-alpine
        ```

        <Tip>
          **Running without a password**

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

          ```shell theme={null}
          docker run --rm -it -p 8123:8123 -e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 clickhouse/clickhouse-server:head-alpine
          ```
        </Tip>
      </Step>

      <Step>
        <h3 id="open-clickstack-ui-docker">
          Open the ClickStack UI
        </h3>

        Open [http://localhost:8123](http://localhost:8123) in your browser and click **ClickStack**.

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

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/deployment/embedded/authenticate.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=4a877ca4ef719f6bb476dfca03f9d628" alt="Authenticate" size="lg" width="3818" height="1938" data-path="images/clickstack/deployment/embedded/authenticate.png" />
      </Step>

      <Step>
        <h3 id="create-a-source-docker">
          Create a source
        </h3>

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

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/deployment/embedded/inferred-source.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=35386373f14a1527bf598a68617e4b60" alt="Create Source" size="lg" width="3820" height="1938" data-path="images/clickstack/deployment/embedded/inferred-source.png" />

        If you don't have data yet, see [Ingesting data](/clickstack/ingesting-data/index) for available options.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Binary">
    <Steps>
      <Step>
        <h3 id="start-clickhouse-binary">
          Start ClickHouse
        </h3>

        Download and start ClickHouse:

        ```shell theme={null}
        curl https://clickhouse.com/ | sh
        ```

        <Accordion title="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:

          ```shell theme={null}
          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` |
        </Accordion>

        Start the server:

        ```shell theme={null}
        ./clickhouse server
        ```
      </Step>

      <Step>
        <h3 id="open-clickstack-ui-binary">
          Open the ClickStack UI
        </h3>

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

      <Step>
        <h3 id="create-a-source-binary">
          Create a source
        </h3>

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

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

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/deployment/embedded/inferred-source.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=35386373f14a1527bf598a68617e4b60" alt="Create Source" size="lg" width="3820" height="1938" data-path="images/clickstack/deployment/embedded/inferred-source.png" />
      </Step>
    </Steps>
  </Tab>
</Tabs>

<h2 id="next-steps">
  Next steps
</h2>

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

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