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 を使用するようになりました。これには、patch を含む 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
# または
docker exec -it some-clickhouse-server clickhouse-client

ClickHouse clientの詳細については、ClickHouse clientを参照してください。

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 インターフェイスを参照してください。

コンテナーの停止と削除

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

ネットワーク

あらかじめ定義されているユーザー 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 @-

上記の例の default ユーザーは、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 command-line arguments を使用して有効にできます:

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 が存在し、現在のユーザーが所有者である必要があります
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 配下に 1 つ以上の *.sql、*.sql.gz、または *.sh スクリプトを追加します。entrypoint が initdb を呼び出した後、サービスの起動前に追加の初期化を行うため、このディレクトリ内で見つかった *.sql ファイルを実行し、実行可能な *.sh スクリプトを実行し、実行可能でない *.sh スクリプトを source します。

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

また、初期化時に 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 = MergeTree
    ORDER BY ();
EOSQL

Get started

Docker を使用した ClickHouse のインストール

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

バージョン

互換性

このイメージの使い方

サーバーインスタンスを起動する

ネイティブクライアントで接続する

curl で接続する

コンテナーの停止と削除

ネットワーク

ボリューム

Linux capabilities

設定

カスタム設定でサーバーインスタンスを起動する

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

root からサーバーを起動する

起動時にデフォルトのデータベースとユーザーを作成する方法

`default` ユーザーの管理

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

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

​バージョン

​互換性

​このイメージの使い方

​サーバーインスタンスを起動する

​ネイティブクライアントで接続する

​curl で接続する

​コンテナーの停止と削除

​ネットワーク

​ボリューム

​Linux capabilities

​設定

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

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

​root からサーバーを起動する

​起動時にデフォルトのデータベースとユーザーを作成する方法

​default ユーザーの管理

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

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

バージョン

互換性

このイメージの使い方

サーバーインスタンスを起動する

ネイティブクライアントで接続する

curl で接続する

コンテナーの停止と削除

ネットワーク

ボリューム

Linux capabilities

設定

カスタム設定でサーバーインスタンスを起動する

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

root からサーバーを起動する

起動時にデフォルトのデータベースとユーザーを作成する方法

`default` ユーザーの管理

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