Docker Compose

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

All ClickStack Open Source components are distributed separately as individual Docker images:

- **ClickHouse**
- **HyperDX**
- **OpenTelemetry (OTel) collector**
- **MongoDB**

These images can be combined and deployed locally using Docker Compose.

Docker Compose exposes additional ports for observability and ingestion based on the default `otel-collector` setup:

- `13133`: Health check endpoint for the `health_check` extension
- `24225`: Fluentd receiver for log ingestion
- `4317`: OTLP gRPC receiver (standard for traces, logs, and metrics)
- `4318`: OTLP HTTP receiver (alternative to gRPC)
- `8888`: Prometheus metrics endpoint for monitoring the collector itself

These ports enable integrations with a variety of telemetry sources and make the OpenTelemetry collector production-ready for diverse ingestion needs.

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

- Local testing
- Proof of concepts
- Production deployments where fault tolerance isn't required and a single server is sufficient to host all ClickHouse data
- When deploying ClickStack but hosting ClickHouse separately e.g. using ClickHouse Cloud.

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

  

Clone the repo

### Clone the repo[​](#clone-the-repo "Direct link to Clone the repo")

To deploy with Docker Compose clone the ClickStack repo, change into the directory and run `docker-compose up`:

```
git clone https://github.com/ClickHouse/ClickStack.git
docker compose up
```

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` data sources will be created for the ClickHouse instance deployed with Docker Compose.

Overriding default connection

You can override the default connection to the integrated ClickHouse instance. For details, see ["Using ClickHouse Cloud"](#using-clickhouse-cloud).

For an example of using an alternative ClickHouse instance, see ["Using ClickHouse Cloud"](#using-clickhouse-cloud).

Complete connection details

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

To connect to the deployed ClickHouse instance, simply click **Create** and accept the default settings.

If you prefer to connect to your own **external ClickHouse cluster** e.g. ClickHouse Cloud, you can manually enter your connection credentials.

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

## Modifying compose settings[​](#modifying-settings "Direct link to Modifying compose settings")

You can modify settings for the stack, such as the version used, through the environment variable file:

```
user@example-host clickstack % cat .env

# Used by docker-compose.yml
IMAGE_NAME_DOCKERHUB=clickhouse/clickstack-all-in-one
LOCAL_IMAGE_NAME_DOCKERHUB=clickhouse/clickstack-local
ALL_IN_ONE_IMAGE_NAME_DOCKERHUB=clickhouse/clickstack-all-in-one
OTEL_COLLECTOR_IMAGE_NAME_DOCKERHUB=clickhouse/clickstack-otel-collector
CODE_VERSION=2.8.0
IMAGE_VERSION_SUB_TAG=.8.0
IMAGE_VERSION=2
IMAGE_NIGHTLY_TAG=2-nightly
IMAGE_LATEST_TAG=latest

# Set up domain URLs
HYPERDX_API_PORT=8000 #optional (should not be taken by other services)
HYPERDX_APP_PORT=8080
HYPERDX_APP_URL=http://localhost
HYPERDX_LOG_LEVEL=debug
HYPERDX_OPAMP_PORT=4320

# Otel/Clickhouse config
HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE=default
```

### Configuring the OpenTelemetry collector[​](#configuring-collector "Direct link to Configuring the OpenTelemetry collector")

The OTel collector configuration can be modified if required - see ["Modifying configuration"](/docs/use-cases/observability/clickstack/ingesting-data/otel-collector#modifying-otel-collector-configuration).

## Using ClickHouse Cloud[​](#using-clickhouse-cloud "Direct link to Using ClickHouse Cloud")

This distribution can be used with ClickHouse Cloud, but it differs from [Managed ClickStack](/docs/use-cases/observability/clickstack/deployment/clickstack-clickhouse-cloud). In this setup, you manage the ClickStack UI yourself while using ClickHouse Cloud only for compute and storage. Unless you have a specific reason to operate the UI independently, we recommend using Managed ClickStack, which includes integrated authentication and additional enterprise features, and removes the need to manage the ClickStack UI yourself.

You should:

- Remove the ClickHouse service from the `docker-compose.yml` file. This is optional if testing, as the deployed ClickHouse instance will simply be ignored - although waste local resources. If removing the service, ensure any references to the service such as `depends_on` are removed.
- Modify the OTel collector to use a ClickHouse Cloud instance by setting the environment variables `CLICKHOUSE_ENDPOINT`, `CLICKHOUSE_USER` and `CLICKHOUSE_PASSWORD` in the compose file. Specifically, add the environment variables to the OTel collector service:

  ```
  otel-collector:
      image: ${OTEL_COLLECTOR_IMAGE_NAME_DOCKERHUB}:${IMAGE_VERSION}
      environment:
        CLICKHOUSE_ENDPOINT: '<CLICKHOUSE_ENDPOINT>' # https endpoint here
        CLICKHOUSE_USER: '<CLICKHOUSE_USER>'
        CLICKHOUSE_PASSWORD: '<CLICKHOUSE_PASSWORD>'
        HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE: ${HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE}
        HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
        OPAMP_SERVER_URL: 'http://app:${HYPERDX_OPAMP_PORT}'
      ports:
        - '13133:13133' # health_check extension
        - '24225:24225' # fluentd receiver
        - '4317:4317' # OTLP gRPC receiver
        - '4318:4318' # OTLP http receiver
        - '8888:8888' # metrics extension
      restart: always
      networks:
        - internal
  ```

  The `CLICKHOUSE_ENDPOINT` should be the ClickHouse Cloud HTTPS endpoint, including the port `8443` e.g. `https://mxl4k3ul6a.us-east-2.aws.clickhouse.com:8443`
- On connecting to the HyperDX UI and creating a connection to ClickHouse, use your Cloud credentials.

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

To set these, modify the relevant services in the `docker-compose.yml`:

```
  app:
    image: ${IMAGE_NAME_DOCKERHUB}:${IMAGE_VERSION}
    ports:
      - ${HYPERDX_API_PORT}:${HYPERDX_API_PORT}
      - ${HYPERDX_APP_PORT}:${HYPERDX_APP_PORT}
    environment:
      BETA_CH_OTEL_JSON_SCHEMA_ENABLED: true # enable JSON
      FRONTEND_URL: ${HYPERDX_APP_URL}:${HYPERDX_APP_PORT}
      HYPERDX_API_KEY: ${HYPERDX_API_KEY}
      HYPERDX_API_PORT: ${HYPERDX_API_PORT}
    # truncated for brevity