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

Docker を使用して ClickHouse をインストールする

Docker Hub のガイドを、 参考のために以下に再掲します。提供されている Docker イメージは、 ClickHouse 用の公式 deb パッケージを利用しています。

Docker pull コマンド:

docker pull clickhouse/clickhouse-server

バージョン​

  • latest タグは、最新の安定ブランチにおける最新リリースを指します。
  • 22.2 のようなブランチタグは、対応するブランチの最新リリースを指します。
  • 22.2.3 や 22.2.3.5 のようなフルバージョンタグは、対応するリリースを指します。
  • head タグは、デフォルトブランチの最新コミットからビルドされたものです。
  • 各タグには、オプションで末尾に -alpine を付けたバリアントがあり、そのイメージが alpine ベースでビルドされていることを示します。

互換性​

  • amd64 イメージには SSE3 命令 のサポートが必要です。 事実上、2005 年以降のほぼすべての x86 CPU は SSE3 をサポートしています。
  • arm64 イメージには ARMv8.2-A アーキテクチャ のサポートと、 さらに Load-Acquire RCpc レジスタが必要です。このレジスタは ARMv8.2-A ではオプションであり、 ARMv8.3-A では必須です。Graviton >=2、Azure、GCP インスタンスでサポートされています。 非対応デバイスの例としては、Raspberry Pi 4 (ARMv8.0-A) や Jetson AGX Xavier/Orin (ARMv8.2-A) があります。
  • ClickHouse 24.11 以降、Ubuntu イメージはベースイメージとして ubuntu:22.04 を使用し始めました。これは パッチ を含む docker バージョン >= 20.10.10 を必要とします。回避策として、代わりに docker run --security-opt seccomp=unconfined を使用できますが、セキュリティ上の影響があります。

このイメージの使い方​

サーバーインスタンスの起動​

docker run -d --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server

デフォルトでは、ClickHouse には Docker ネットワーク経由でのみアクセスできます。ネットワーク設定については、以下のセクションを参照してください。

デフォルトでは、上記のサーバーインスタンスは、パスワードなしの default ユーザーとして実行されます。

ネイティブクライアントを使って接続する​

docker run -it --rm --network=container:some-clickhouse-server --entrypoint clickhouse-client clickhouse/clickhouse-server
# OR
docker exec -it some-clickhouse-server clickhouse-client

ClickHouse クライアントの詳細については、ClickHouse クライアント を参照してください。

curl で接続する​

echo "SELECT 'Hello, ClickHouse!'" | docker run -i --rm --network=container:some-clickhouse-server buildpack-deps:curl curl 'http://localhost:8123/?query=' -s --data-binary @-

HTTP インターフェースの詳細については、ClickHouse HTTP Interface を参照してください。

コンテナの停止および削除​

docker stop some-clickhouse-server
docker rm some-clickhouse-server

ネットワーキング​

注記

事前定義されたユーザー default は、パスワードが設定されていない限りネットワークにアクセスできません。 下記の「起動時に default データベースとユーザーを作成する方法」と「default ユーザーの管理」を参照してください。

Docker コンテナで稼働している ClickHouse を公開するには、コンテナ内部のポートをホスト側のポートに特定のポートをマッピングします。

docker run -d -p 18123:8123 -p19000:9000 -e CLICKHOUSE_PASSWORD=changeme --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server
echo 'SELECT version()' | curl 'http://localhost:18123/?password=changeme' --data-binary @-

または、--network=host を使用してコンテナにホストポートを直接利用させることで （ネットワークパフォーマンスをさらに向上させることもできます）：

docker run -d --network=host --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server
echo 'SELECT version()' | curl 'http://localhost:8123/' --data-binary @-
注記

上記の例で設定しているデフォルトユーザーは、localhost からのリクエストに対してのみ有効です

ボリューム​

データの永続化を確保するために、通常はコンテナ内に次のディレクトリをマウントします。

  • /var/lib/clickhouse/ - ClickHouse がデータを保存するメインディレクトリ
  • /var/log/clickhouse-server/ - ログ
docker run -d \
    -v "$PWD/ch_data:/var/lib/clickhouse/" \
    -v "$PWD/ch_logs:/var/log/clickhouse-server/" \
    --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server

次のディレクトリもマウントすることを検討してください:

  • /etc/clickhouse-server/config.d/*.xml - サーバー設定を調整するためのファイル
  • /etc/clickhouse-server/users.d/*.xml - ユーザー設定を調整するためのファイル
  • /docker-entrypoint-initdb.d/ - データベース初期化スクリプトを格納したディレクトリ（以下を参照）。

Linux ケーパビリティ​

ClickHouse には高度な機能がいくつかあり、その一部を利用するには複数の Linux ケーパビリティ を有効化する必要があります。

これらは必須ではありませんが、次の Docker のコマンドライン引数 を使用して有効化できます。

docker run -d \
    --cap-add=SYS_NICE --cap-add=NET_ADMIN --cap-add=IPC_LOCK \
    --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server

詳細については "Docker での CAP_IPC_LOCK と CAP_SYS_NICE ケーパビリティの設定" を参照してください。

設定​

コンテナは、HTTP インターフェイス 用にポート 8123 を、ネイティブクライアント 用にポート 9000 を公開します。

ClickHouse の設定は「config.xml」ファイルによって定義されます（ドキュメント）。

カスタム構成でサーバーインスタンスを起動する​

docker run -d --name some-clickhouse-server --ulimit nofile=262144:262144 -v /path/to/your/config.xml:/etc/clickhouse-server/config.xml clickhouse/clickhouse-server

カスタムユーザーでサーバーを起動する​

# $PWD/data/clickhouse should exist and be owned by current user
docker run --rm --user "${UID}:${GID}" --name some-clickhouse-server --ulimit nofile=262144:262144 -v "$PWD/logs/clickhouse:/var/log/clickhouse-server" -v "$PWD/data/clickhouse:/var/lib/clickhouse" clickhouse/clickhouse-server

ローカルディレクトリをマウントしてイメージを使用する場合、適切なファイル所有権を維持するためにユーザーを指定しておくことをお勧めします。--user 引数を使用し、コンテナ内に /var/lib/clickhouse と /var/log/clickhouse-server をマウントしてください。これを行わないと、イメージがエラーとなり起動しません。

ルートからサーバーを起動する​

ユーザーネームスペースが有効になっている場合、root ユーザーとしてサーバーを起動するのが便利です。 そのためには、次を実行します:

docker run --rm -e CLICKHOUSE_RUN_AS_ROOT=1 --name clickhouse-server-userns -v "$PWD/logs/clickhouse:/var/log/clickhouse-server" -v "$PWD/data/clickhouse:/var/lib/clickhouse" clickhouse/clickhouse-server

起動時に default データベースとユーザーを作成する方法​

コンテナの起動時に、ユーザー（既定では default という名前のユーザーが使用されます）とデータベースを作成したい場合があります。これは、環境変数 CLICKHOUSE_DB、CLICKHOUSE_USER、CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT、CLICKHOUSE_PASSWORD を設定することで行えます。

docker run --rm -e CLICKHOUSE_DB=my_database -e CLICKHOUSE_USER=username -e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 -e CLICKHOUSE_PASSWORD=password -p 9000:9000/tcp clickhouse/clickhouse-server

default ユーザーの管理​

CLICKHOUSE_USER、CLICKHOUSE_PASSWORD、CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT のいずれも設定されていない場合、default ユーザーへのネットワーク経由でのアクセスはデフォルトで無効化されています。

環境変数 CLICKHOUSE_SKIP_USER_SETUP を 1 に設定することで、default ユーザーをセキュアではない形で利用可能にする方法もあります。

docker run --rm -e CLICKHOUSE_SKIP_USER_SETUP=1 -p 9000:9000/tcp clickhouse/clickhouse-server

このイメージを拡張する方法​

このイメージを基にした派生イメージで追加の初期化処理を行うには、/docker-entrypoint-initdb.d 配下に 1 つ以上の *.sql、*.sql.gz、または *.sh スクリプトを追加します。entrypoint が initdb を呼び出した後、そのディレクトリ内で見つかった *.sql ファイルをすべて実行し、実行可能な *.sh スクリプトをすべて実行し、実行不可の *.sh スクリプトはすべて source コマンドで読み込んで、サービスを起動する前にさらに初期化を行います。

注記

/docker-entrypoint-initdb.d 配下のスクリプトは、ファイル名の アルファベット順 に実行されます。スクリプト同士に依存関係がある場合（たとえば、VIEW を作成するスクリプトは、参照されるテーブルを作成するスクリプトの後に実行する必要があるなど）、ファイル名が正しい順序でソートされるようにしてください。

また、初期化中に clickhouse-client で使用される環境変数 CLICKHOUSE_USER と CLICKHOUSE_PASSWORD を指定することもできます。

たとえば、別のユーザーとデータベースを追加するには、次の内容を /docker-entrypoint-initdb.d/init-db.sh に追加します。

#!/bin/bash
set -e

clickhouse client -n <<-EOSQL
    CREATE DATABASE docker;
    CREATE TABLE docker.docker (x Int32) ENGINE = Log;
EOSQL