Contents
前提条件と環境チェック
ローカルで ClickHouse を手軽に試すには、まず Docker と Docker Compose が正しくインストールされていることを確認します。Docker のバージョンが古いとイメージ取得やネットワーク設定で予期せぬエラーになるため、最低要件 : Docker ≥ 20.10 / Compose ≥ 1.29 を満たすかどうかをチェックしてください。本節ではバージョン確認コマンドと、要件未達時の対処方法をまとめます。
Docker と Docker Compose のバージョン確認
Docker 本体のバージョンは次のコマンドで取得できます。
|
1 2 3 |
docker --version # 例: Docker version 24.0.5, build abcdefg |
Compose はプラグイン版 (docker compose) と従来のスタンドアロン版 (docker‑compose) の両方が利用可能です。どちらでも下記でバージョンを確認できます。
|
1 2 3 4 5 6 |
# Docker Desktop 付属のプラグイン版の場合 docker compose version # 従来版（Linux/macOS/Windows）を使用している場合 docker-compose --version |
- ポイント
- バージョンが要件未満の場合は、Docker公式サイト の手順に従い最新バージョンへ更新してください。
- Docker Desktop を利用している環境では「設定」→「General」から自動アップデートを有効化すると、常に最新版が保たれます。
ClickHouse 公式イメージの取得と docker run 実行
このセクションでは、ClickHouse の公式 Docker イメージ（タグ固定）を取得し、永続化・認証設定付きでコンテナを直接起動するまでの流れを解説します。Docker Compose を使わずに単体コンテナだけで手軽に試したいときに有効です。
イメージのプルとタグ指定
公式リポジトリから特定バージョン（例 : 23.11）を明示的に取得します。latest タグは自動更新されるため、再現性が失われやすい点に注意してください。
|
1 2 |
docker pull clickhouse/clickhouse-server:23.11 |
ポート公開・ボリュームマウント・環境変数設定例
ClickHouse のデフォルトポートは 9000（TCP） と 8123（HTTP） です。永続化と初期ユーザー作成のために、以下のオプションを付与してコンテナを起動します。
|
1 2 3 4 5 6 7 8 9 |
docker run -d \ --name clickhouse_server \ -p 9000:9000 -p 8123:8123 \ -v $(pwd)/clickhouse_data:/var/lib/clickhouse \ -e CLICKHOUSE_USER=admin \ -e CLICKHOUSE_PASSWORD=StrongPass123! \ -e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 \ clickhouse/clickhouse-server:23.11 |
-p… ホストとコンテナのポートマッピング。-v… データ永続化用ディレクトリをローカルにバインドマウント。-e… 初期ユーザー・パスワード、認証有効化用環境変数。
Windows でのボリュームマウント例
Windows のコマンドプロンプト（cmd.exe）と PowerShell では、バインドマウントの書式が Linux と異なります。以下にそれぞれの記法を示します。
| シェル | マウント指定例 |
|---|---|
| cmd | -v %cd%\clickhouse_data:/var/lib/clickhouse |
| PowerShell | -v ${PWD}\clickhouse_data:/var/lib/clickhouse |
※注意：Windows ではファイルシステムが NTFS のため、Linux 固有の UID（後述の
101）に対応した権限設定は自動的に行われません。パーミッションエラーを防ぐには、コンテナ起動直後にclickhouse-serverユーザーで書き込み可能かどうか確認してください。
UID = 101 の扱いについて（Linux 以外への注意喚起）
公式イメージでは ClickHouse プロセスが UID 101 のユーザーで実行されます。Linux ホスト上では永続化ディレクトリの所有者を同じ UID に合わせることで Permission denied を回避できますが、macOS や Windows など Linux 以外の環境では UID が無視されるかマッピングが不完全になることがあります。そのため：
- Linux：
sudo chown -R 101:101 ./clickhouse_dataが推奨です。 - macOS / Windows：所有者変更は不要ですが、コンテナ内部で書き込み権限が不足している場合は
chmod 777等の緩めたパーミッションを一時的に適用し、動作確認後に必要最小限へ戻すことを推奨します。
Docker Compose での構成ファイル作成
複数サービスや設定変更が頻繁に発生する場合は docker‑compose.yml が便利です。本節では最小構成サンプルと、起動・停止・ログ確認までのフローを解説します。
docker-compose.yml のサンプル
以下は ClickHouse サーバー単体の構成例です。環境変数・永続化ボリューム・初期化スクリプト用ディレクトリが含まれています。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
version: "3.9" services: clickhouse-server: image: clickhouse/clickhouse-server:23.11 container_name: ch_server ports: - "8123:8123" - "9000:9000" environment: CLICKHOUSE_USER: admin CLICKHOUSE_PASSWORD: StrongPass123! CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1 volumes: # データ永続化（Linux の場合は UID=101 に合わせる） - ./clickhouse_data:/var/lib/clickhouse # 初期化スクリプト格納ディレクトリ（任意） - ./initdb:/docker-entrypoint-initdb.d |
container_nameを明示すると、docker exec -it ch_server …のように名前だけで操作でき便利です。volumesの 2 番目は起動時に自動実行されるスクリプトを置くための領域です。
起動手順とコンテナ確認
|
1 2 3 4 |
docker compose up -d # バックグラウンドで全サービス起動 docker ps # 実行中コンテナ一覧 docker logs ch_server # ログ出力で起動状態をチェック |
ログに Ready for connections が表示されれば、サーバーは正常に稼働しています。
- ポイント
- 開発環境のリセットが必要なときは
docker compose down -vでコンテナ本体と永続化ボリュームを同時に削除できます。
初期化スクリプトと永続化設定
ClickHouse コンテナ起動時に自動実行される /docker-entrypoint-initdb.d/ 配下のファイルは、データベースやユーザーの事前作成に便利です。本節ではシェルスクリプト例と、永続化ディレクトリの権限設定・バックアップ手順を詳しく解説します。
/docker-entrypoint-initdb.d/ に置くスクリプト例
以下は ./initdb/init-db.sh として保存し、Compose のボリュームでマウントするサンプルです。実行権限が必要な点に注意してください。
|
1 2 3 4 5 6 7 8 9 |
#!/bin/bash set -e # 環境変数から取得した admin ユーザーでデータベース作成 clickhouse-client --user=admin --password=StrongPass123! <<EOF CREATE DATABASE IF NOT EXISTS analytics; GRANT ALL ON analytics.* TO admin; EOF |
|
1 2 |
chmod +x initdb/init-db.sh # 実行権限付与（忘れがちなので必ず実施） |
- このスクリプトはコンテナ起動直後に 1 回だけ実行され、
analyticsデータベースと管理者権限を自動で設定します。
永続化ディレクトリの権限とバックアップ方法
Linux 環境の場合（UID 101 の所有者合わせ）
|
1 2 3 |
sudo mkdir -p ./clickhouse_data sudo chown -R 101:101 ./clickhouse_data |
macOS / Windows 環境の場合（パーミッション緩和例）
|
1 2 3 |
mkdir -p ./clickhouse_data chmod 777 ./clickhouse_data # 開発段階のみ推奨。運用時は適切に絞り込むこと。 |
バックアップの基本フロー（tar を利用）
- コンテナ内部でデータディレクトリを圧縮
- ホストへコピーして保存
|
1 2 3 |
docker exec -t ch_server tar czf /tmp/ch_backup.tar.gz /var/lib/clickhouse docker cp ch_server:/tmp/ch_backup.tar.gz ./clickhouse_backup_$(date +%F).tar.gz |
- 増分バックアップ が必要な場合は
rsync --link-destを併用すると効率的です。 - バックアップ取得は、書き込みが少ない時間帯（例 : 夜間メンテナンスウィンドウ）に実施するのが安全です。
設定ファイル (config.xml) のカスタマイズ
ClickHouse の細かなチューニングは config.xml で行います。Docker 環境でもホスト側に設定ファイルを置き、ボリュームマウントすることで簡単に反映できます。
カスタム設定例（メモリ上限とロギング）
|
1 2 3 4 5 6 7 |
services: clickhouse-server: ... volumes: - ./clickhouse_data:/var/lib/clickhouse - ./custom_config/config.xml:/etc/clickhouse-server/config.xml |
./custom_config/config.xml の抜粋例：
|
1 2 3 4 5 6 7 8 9 |
<yandex> <max_server_memory_usage>8589934592</max_server_memory_usage> <!-- 8 GB --> <logger> <level>information</level> <log>/var/log/clickhouse-server/clickhouse.log</log> <errorlog>/var/log/clickhouse-server/error.log</errorlog> </logger> </yandex> |
max_server_memory_usageはサーバーが使用できる最大メモリ量をバイト単位で指定します。- ログ出力先はコンテナ内のディレクトリにマウントすれば、ホスト側でも確認できます（例 :
./clickhouse_logs:/var/log/clickhouse-server）。
動作確認と基本クエリ実行
サーバーが起動したら、clickhouse-client を使って接続テストを行います。ローカルにクライアントをインストールする方法と、コンテナ内部から直接実行する方法の両方を紹介します。
コンテナ内部から clickhouse-client を起動
|
1 2 3 |
docker exec -it ch_server clickhouse-client \ --user=admin --password=StrongPass123! |
対話モードが開始され、以下のようにバージョン情報が表示されれば成功です。
|
1 2 |
Connected to ClickHouse server version 23.11. |
ホスト側にクライアントをインストールして外部接続
-
macOS（Homebrew）
bash
brew install clickhouse-client
clickhouse-client -h localhost -u admin -p -
Windows（Chocolatey）
powershell
choco install clickhouse-cli
clickhouse-client.exe -h localhost -u admin -p
SELECT クエリサンプル
|
1 2 |
SELECT number FROM system.numbers LIMIT 10; |
期待される出力は 0,1,2,…,9 の十行です。これで列指向データベースの高速ストリーミングが確認できます。
- ポイント
- ポート
9000が正しくマッピングされていないと「Connection refused」になるため、docker psやdocker compose configでポート設定を必ず再チェックしてください。
トラブルシューティングと拡張構成例
実運用に近づくにつれて環境固有のエラーやパフォーマンス課題が顕在化します。本節では代表的なトラブルケースとその対処法、さらにマルチコンテナ構成やクラウド向けの留意点をまとめます。
よくあるエラーと解決策
| エラーメッセージ | 主な原因 | 推奨対処 |
|---|---|---|
Address already in use (ポート競合) |
ホスト上で 9000/8123 が他プロセスに占有されている | docker ps で占有コンテナを確認し、-p 19000:9000 のように別ポートへリダイレクト |
Permission denied on /var/lib/clickhouse |
永続化ディレクトリの所有者が UID 101 と不一致（Linux）または Windows/macOS の権限不足 | Linux は sudo chown -R 101:101 ./clickhouse_data、他 OS は一時的に chmod 777 後に絞り込み |
cannot allocate memory |
Docker のメモリ上限がデフォルトの 2 GB 以下に設定されている | Docker Desktop → Settings → Resources でメモリを 4 GB 以上に増やす |
ClickHouse server is not ready (起動待ち) |
初期化スクリプトの実行時間が長い、またはディスク I/O が逼迫している | docker logs -f ch_server で完了まで待機し、Compose の restart: unless-stopped を追加 |
- ポイント
- エラーログは必ず
docker logs <コンテナ名>で取得し、公式ドキュメントのトラブルシューティング項目と照合してください。
複数サービス構成例（サーバー＋クライアント）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
version: "3.9" services: server: image: clickhouse/clickhouse-server:23.11 container_name: ch_server ports: ["8123:8123","9000:9000"] volumes: - ./clickhouse_data:/var/lib/clickhouse - ./initdb:/docker-entrypoint-initdb.d environment: CLICKHOUSE_USER: admin CLICKHOUSE_PASSWORD: StrongPass123! CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1 client: image: clickhouse/clickhouse-client:23.11 container_name: ch_client depends_on: [server] entrypoint: ["sleep","infinity"] # 起動後は `docker exec -it ch_client clickhouse-client …` で使用 |
- 利点
- CI/CD パイプラインや自動テストでクライアントだけを呼び出すことができ、サーバーの再起動やデータリセットと分離して実行できます。
クラウドデプロイ時の留意点
| 項目 | 推奨設定 |
|---|---|
| ネットワーク | VPC 内で内部 IP のみ公開し、外部からは VPN または ALB 経由でアクセス |
| ストレージ | 高スループット SSD（例 : AWS gp3）を /var/lib/clickhouse にマウント |
| CPU/メモリ | OLAP クエリ向けに最低 4 コア、8 GB メモリ以上を確保 |
| バックアップ | EBS スナップショットや clickhouse-backup ツールで定期的に取得 |
| オーケストレーション | 本番環境では Kubernetes の Helm チャート（公式提供）を利用し、Compose からコード化されたマニフェストへ移行 |
- ポイント
- Docker Compose はローカル開発やステージング向けに最適です。クラウド本番環境では、リソース自動スケーリングやサービスディスカバリーを活用できる Kubernetes への移行を検討してください。
本記事のまとめ
- 前提条件：Docker ≥ 20.10 と Compose ≥ 1.29 がインストールされているか確認し、必要に応じて最新版へ更新。
- イメージ取得と単体起動：タグを固定して公式イメージ
clickhouse/clickhouse-server:23.11をプルし、ポート・永続化ボリューム・認証環境変数でコンテナを立ち上げる。Windows でも%cd%/${PWD}を利用したマウント例を提示。 - Docker Compose：最小構成の
docker-compose.ymlを作成し、docker compose up -dで一括起動・down -vでリセット可能。 - 初期化スクリプトと永続化：
/docker-entrypoint-initdb.d/に配置したシェルでデータベース作成、Linux は UID 101 の所有権付与、非 Linux はパーミッション緩和の注意点を明記。バックアップは tar または rsync で取得。 - 設定ファイルカスタマイズ：
config.xmlをホスト側からボリュームマウントし、メモリ上限やロギングを調整できることを紹介。 - 動作確認：コンテナ内部・外部クライアントの両方で接続テストし、
system.numbersクエリで基本的な稼働を検証。 - トラブルシューティングと拡張構成：代表的エラーと対処法、マルチコンテナ構成例、クラウドデプロイ時のベストプラクティスを網羅。
これらの手順を踏めば、数分でローカル環境に ClickHouse を構築し、サンプルクエリで動作確認が完了します。次回はパフォーマンスチューニングやクラスタリング構成について詳しく解説する予定ですので、お楽しみに！