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

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 client を参照してください。

curl で接続する​

echo "SELECT 'こんにちは、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 capabilities​

ClickHouse には、複数の Linux capabilities の有効化を必要とする高度な機能があります。

これらは必須ではなく、次の 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 が存在し、現在のユーザーが所有者である必要があります \{#pwddataclickhouse-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 でサーバーを起動する​

ユーザーネームスペースが有効になっている場合、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 という名前のユーザーが使用されます）とデータベースを作成したい場合には、環境変数 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 配下に *.sql、*.sql.gz、または *.sh スクリプトを 1 つ以上追加します。エントリポイントが initdb を呼び出した後、そのディレクトリ内にあるすべての *.sql ファイルを実行し、実行可能な *.sh スクリプトを実行し、実行可能でない *.sh スクリプトは読み込んで（source して）、サービスを起動する前にさらに初期化処理を行います。
また、初期化中に 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