メインコンテンツまでスキップ
メインコンテンツまでスキップ

ClickHouseをDockerでインストールする

便利のために、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

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

コンテナの停止 / 削除​

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 @-
注記

上記の例のデフォルトユーザーは、ローカルホストのリクエストのみに使用可能です。

ボリューム​

通常、永続性を達成するために、以下のフォルダーをコンテナ内にマウントすることをお勧めします：

  • /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が存在し、現在のユーザーが所有している必要があります
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という名前のユーザー）がデータベースを作成したい場合があります。環境変数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ユーザーの管理​

ユーザーdefaultは、CLICKHOUSE_USER、CLICKHOUSE_PASSWORD、またはCLICKHOUSE_DEFAULT_ACCESS_MANAGEMENTが設定されていない場合、デフォルトでネットワークアクセスが無効になっています。

環境変数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スクリプトを追加します。エントリポイントがinitdbを呼び出すと、そのディレクトリにある*.sqlファイルが実行され、実行可能な*.shスクリプトが実行され、非実行可能な*.shスクリプトがソースされて、サービスが開始される前に更なる初期化が行われます。
また、初期化中に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