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

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

以下に便利なようにDocker Hubのガイドを再現しました。利用可能なDockerイメージは、公式のClickHouse debパッケージを利用しています。

Dockerプルコマンド：

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 '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ユーザーの管理」を参照してください。

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の機能​

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

カスタムユーザーとしてサーバーを起動する​

ローカルディレクトリをマウントしたイメージを使用する場合、適切なファイル所有権を維持するためにユーザーを指定することをお勧めします。--user引数を使用し、コンテナ内に/var/lib/clickhouseおよび/var/log/clickhouse-serverをマウントします。そうしないと、イメージは不満を言い、起動しません。

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

ルートからサーバーを起動することは、ユーザー名前空間が有効な場合に便利です。 そのためには、次のように実行します：

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に以下を追加します：