メインコンテンツへスキップ
メインコンテンツへスキップ

Docker Compose

すべての ClickStack オープンソースコンポーネントは、個別の Docker イメージとして配布されています:

  • ClickHouse
  • HyperDX
  • OpenTelemetry (OTel) collector
  • MongoDB

これらのイメージは、Docker Compose を使用してローカル環境に組み合わせてデプロイできます。

Docker Compose は、デフォルトの otel-collector セットアップに基づき、オブザーバビリティおよびインジェスト用の追加ポートを公開します:

  • 13133: health_check extension 用のヘルスチェックエンドポイント
  • 24225: ログインジェスト用の Fluentd レシーバー
  • 4317: OTLP gRPC レシーバー（トレース、ログ、メトリクスの標準）
  • 4318: OTLP HTTP レシーバー（gRPC の代替）
  • 8888: コレクター自体を監視するための Prometheus メトリクスエンドポイント

これらのポートにより、さまざまなテレメトリソースとの統合が可能になり、OpenTelemetry collector を多様なインジェスト要件に対応した本番環境向けとして利用できるようになります。

適した用途​

  • ローカルテスト
  • PoC（概念実証）
  • フォールトトレランスが不要で、単一サーバーで全ての ClickHouse データをホストできる本番環境へのデプロイメント
  • ClickStack をデプロイしつつ、ClickHouse は別でホスティングする場合（例: ClickHouse Cloud を使用する場合）

デプロイ手順​


リポジトリをクローンする​

Docker Compose でデプロイするには、ClickStack リポジトリをクローンし、そのディレクトリに移動して docker-compose up を実行します:

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

http://localhost:8080 にアクセスして HyperDX UI を開きます。

ユーザーを作成し、要件を満たすユーザー名とパスワードを設定します。

Create をクリックすると、Docker Compose でデプロイされた ClickHouse インスタンス向けのデータソースが作成されます。

Overriding default connection

組み込みの ClickHouse インスタンスへのデフォルト接続を上書きできます。詳細については、「Using ClickHouse Cloud」を参照してください。

HyperDX UI

代替の ClickHouse インスタンスを使用する例については、「Using ClickHouse Cloud」を参照してください。

接続情報を入力する​

デプロイ済みの ClickHouse インスタンスに接続するには、Create をクリックしてデフォルト設定をそのまま使用します。

独自の 外部 ClickHouse クラスター（例: ClickHouse Cloud）へ接続したい場合は、接続用の認証情報を手動で入力できます。

ソースの作成を求められた場合は、すべてのデフォルト値を維持し、Table フィールドに otel_logs を入力します。他の設定は自動検出されるはずなので、Save New Source をクリックできます。

Create logs source

Compose 設定の変更​

環境変数ファイルを使って、使用するバージョンなどスタックの設定を変更できます。

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

OpenTelemetry collector の設定​

必要に応じて OTel collector の設定を変更できます。詳細は「設定の変更」を参照してください。

ClickHouse Cloud の使用​

このディストリビューションは ClickHouse Cloud と併用できますが、Managed ClickStack とは異なります。この構成では、ClickStack UI は自分で管理し、ClickHouse Cloud はコンピュートおよびストレージのみに使用します。特別な理由がない限り UI を独立運用する必要はないため、認証の統合や追加のエンタープライズ機能が含まれ、ClickStack UI を自分で管理する必要がなくなる Managed ClickStack の利用を推奨します。

次の作業を行ってください:

  • docker-compose.yml ファイルから ClickHouse サービスを削除します。これはテスト用途であれば任意です。デプロイされた ClickHouse インスタンスは単に無視されますが、ローカルリソースを消費します。サービスを削除する場合は、depends_on などそのサービスへの参照も削除してください。

  • compose ファイル内で環境変数 CLICKHOUSE_ENDPOINT、CLICKHOUSE_USER、CLICKHOUSE_PASSWORD を設定し、OTel collector が ClickHouse Cloud インスタンスを使用するように変更します。具体的には、これらの環境変数を OTel collector サービスに追加します:

    otel-collector:
    image: ${OTEL_COLLECTOR_IMAGE_NAME_DOCKERHUB}:${IMAGE_VERSION}
    environment:
      CLICKHOUSE_ENDPOINT: '<CLICKHOUSE_ENDPOINT>' # ここに HTTPS エンドポイントを指定
      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 拡張機能
      - '24225:24225' # fluentd レシーバー
      - '4317:4317' # OTLP gRPC レシーバー
      - '4318:4318' # OTLP HTTP レシーバー
      - '8888:8888' # メトリクス拡張機能
    restart: always
    networks:
      - internal

    CLICKHOUSE_ENDPOINT には、ポート 8443 を含む ClickHouse Cloud の HTTPS エンドポイントを指定します。例: https://mxl4k3ul6a.us-east-2.aws.clickhouse.com:8443

  • HyperDX UI に接続し、ClickHouse への接続を作成する際には、ClickHouse Cloud の認証情報を使用します。

JSON 型サポート​

Beta feature. Learn more.
ベータ機能 - 本番環境向けではありません

ClickStack における JSON 型サポートは ベータ機能 です。JSON 型自体は ClickHouse 25.3+ では本番環境向けとして利用可能ですが、ClickStack との統合はまだ積極的に開発中であり、制限があったり、将来的に変更されたり、不具合を含む可能性があります。

ClickStack では、バージョン 2.0.4 以降で JSON 型 をベータ機能としてサポートしています。

この型の利点については JSON 型の利点 を参照してください。

JSON 型のサポートを有効にするには、以下の環境変数を設定する必要があります。

  • OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' - OTel collector でのサポートを有効にし、スキーマが JSON 型を使用して作成されるようにします。
  • BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true (ClickStack オープンソース版のみ) - ClickStack UI アプリケーションでのサポートを有効にし、JSON データに対してクエリを実行できるようにします。

これらを設定するには、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

  otel-collector:
    image: ${OTEL_COLLECTOR_IMAGE_NAME_DOCKERHUB}:${IMAGE_VERSION}
    environment:
      OTEL_AGENT_FEATURE_GATE_ARG: '--feature-gates=clickhouse.json' # enable JSON
      CLICKHOUSE_ENDPOINT: 'tcp://ch-server:9000?dial_timeout=10s' 
      # truncated for brevity