00 セットアップ

クラウドサービスを作成し、ローカルのクライアントをインストールし、エージェントを一度だけ接続して、ローカルアプリを起動します。

始める前に、ページヘッダーで macOS か Windows を選んでください。選択内容はワークショップ全体で保持されます。Windows では WSL 2 上の Ubuntu を使うので、同じ Bash、Docker、ClickHouse、エージェントのコマンドがすべてのモジュールで動作します。

成果

約 25分 で、次の状態になります。

ClickHouse Cloud サービスと組織 API キーがある
clickhousectl と clickhouse データベースクライアントが入っている
コーディングエージェントに ClickHouse スキルと、ClickHouse および ClickStack の MCP 接続がある
Langfuse と OpenAI のキーがある
アプリが localhost:8080 で正常に動いている

ClickHouse、Postgres、ClickPipes、ClickStack/HyperDX、Langfuse、MCP のエンドポイントはクラウドでホストされています。自分のマシンで動くのは、ワークショップアプリ、CLI／クライアントツール、コーディングエージェント、負荷生成器、ステートレスなテレメトリコレクターだけです。

ステップ 2 以降は、特に指定がない限りすべてのコマンドをアプリディレクトリから実行してください。

ステップ 1 — 前提条件を確認する

メモリを 6 GB 以上割り当てた Docker、Git、Node.js 22+、Python 3、そして MCP 対応のコーディングエージェント1つ（Claude Code、Cursor、Codex CLI、または Windsurf）が必要です。

macOS のセットアップ

Docker Desktop for Mac をインストールし、Settings -> Resources で 6 GB 以上を割り当ててください。ターミナルを開いて次を実行します。

docker version
docker compose version
git --version
node --version
python3 --version

すべてのコマンドがバージョンを出力し、docker version が Client と Server の両セクションを表示してから次に進んでください。

会社管理のノート PC ですか？

会社のポリシーによって MCP のインストールやブラウザ OAuth が禁止されている場合があります。ステップ 7 の OAuth が開けない場合は、個人のマシンを使うか管理者に相談してください。

ステップ 2 — リポジトリをクローンしてワークショップブランチに切り替える

macOS のターミナルで次を実行します。

git clone https://github.com/ClickHouse/ClickHouse_Demos.git
cd ClickHouse_Demos
git switch build-workshop-v1
cd workshops/build_workshop/app
cp .env.workshop.example .env.workshop

このターミナルは ClickHouse_Demos/workshops/build_workshop/app に置いたままにしてください。 Windows では Ubuntu のターミナルを意味します。preflight スクリプトは このディレクトリ内の ./preflight.sh です。モジュール 07 の障害テスト中を除き、 build-workshop-v1 に留まってください。いまブランチを確認します。

git branch --show-current

期待される出力: build-workshop-v1。

ステップ 3 — ClickHouse Cloud アカウントと API キーを作成する

ワークショップ当日より前に: 3つのアカウントをすべて作成してください

日程が決まったワークショップに参加する場合は、ClickHouse Cloud、Langfuse、OpenAI のアカウントを事前に作成しておいてください。それぞれの登録で、メールや電話の確認待ちに 5〜10分かかることがあります。演習で使うキーとリソースの作成は、セットアップのときにこのページに戻って行います。

対面トレーニングの場合: トレーナーから安全な方法で提供される受講者専用の ClickHouse Cloud 組織 API キーを使い、このステップはスキップしてください。

console.clickhouse.cloud でサインインするか、トライアルを開始します。
API Keys を開き、Admin 権限の組織キーを作成して、Key ID とシークレットを保存します。

シークレットは一度しか表示されません。リポジトリの外に保存し、.env.workshop には入れないでください。

ステップ 4 — `clickhousectl` をインストールする

curl https://clickhouse.com/cli | sh
export PATH="$HOME/.local/bin:$PATH"
clickhousectl --version

新しいターミナルで clickhousectl が見つからない場合は、シェルのプロファイルに ~/.local/bin を追加してください。Windows では Ubuntu の中でインストールして実行します。 PowerShell で Windows 用の実行ファイルを使わないでください。

ステップ 5 — `clickhousectl` を認証する

ステップ 3 の API キーを使います。対話形式ならシークレットがシェルの履歴に残りません。

clickhousectl cloud auth login --interactive

信頼できる自動化では、CLI が想定する明示的な形式を使えます。

clickhousectl cloud auth login --api-key <key> --api-secret <secret>

保存された認証情報と Cloud へのアクセスの両方を確認します。

clickhousectl cloud auth status
clickhousectl cloud org list

clickhousectl はプロジェクトの認証情報をカレントディレクトリの .clickhouse/ 以下に保存します。 Cloud コマンドはアプリディレクトリから実行し続け、このフォルダーは絶対にコミットも共有もしないでください。

ステップ 6 — ClickHouse サービスを作成する

モジュール 03 で Postgres にも使うリージョンを選んでください。必要に応じて例のリージョンを置き換えます。

clickhousectl cloud service create \
  --name my-workshop-clickhouse \
  --provider aws \
  --region ap-southeast-1 \
  --min-replica-memory-gb 8 \
  --max-replica-memory-gb 8 \
  --num-replicas 1 \
  --idle-scaling true \
  --idle-timeout-minutes 15

返ってきた service ID と一度だけ表示される default ユーザーのパスワード を保存します。準備できたか確認します。

clickhousectl cloud service list
clickhousectl cloud service get <service-id>

Cloud サービスと同じメジャー／マイナーリリースのクライアントをインストールしてください。少し古い Cloud サーバーに対して新しい stable クライアントを使うと出る、未知の設定に関する警告を避けられます。

CLICKHOUSE_VERSION=$(clickhousectl cloud service query \
  --id <service-id> \
  --format TabSeparatedRaw \
  --query "SELECT version()")
CLICKHOUSE_SERIES=$(printf '%s\n' "$CLICKHOUSE_VERSION" | cut -d. -f1,2)
clickhousectl local use "$CLICKHOUSE_SERIES"
clickhouse client --version

local use はクライアントのバイナリだけをインストールし、ClickHouse サーバーは起動しません。ワークショップのクエリはすべて ClickHouse Cloud を対象にします。サービスの Connect ダイアログからホスト名をコピーし、クライアントを検証します。--password フラグはパスワードを画面に表示せずに入力を求めます。

cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app"
workshop_env() { sed -n "s/^$1=//p" .env.workshop | tail -n 1; }
CLICKHOUSE_HOST=$(workshop_env CLICKHOUSE_HOST)
CLICKHOUSE_USER=$(workshop_env CLICKHOUSE_USER)
CLICKHOUSE_PASSWORD=$(workshop_env CLICKHOUSE_PASSWORD)
unset -f workshop_env

clickhouse client \
  --host "$CLICKHOUSE_HOST" \
  --secure \
  --user "$CLICKHOUSE_USER" \
  --password "$CLICKHOUSE_PASSWORD" \
  --query "SELECT version(), currentUser()"

期待される出力: ClickHouse のバージョンと default を含む1行。

ステップ 7 — エージェントのスキルと2つの MCP サーバーを一度だけ設定する

これらの連携にはそれぞれ役割があります。

連携	目的	使うモジュール
ClickHouse skills	スキーマと SQL を ClickHouse のプラクティスに照らしてレビューする	モジュール 01 と 03
ClickHouse MCP (`/mcp`)	`SELECT` クエリで自分のサービスを読む	モジュール 01 と 04
ClickStack MCP (`/clickstack`)	テレメトリを検索し、SRE の成果物を保存する	モジュール 06 と 07

まず、自分のエージェント用にスキルをインストールします。

clickhousectl skills --agent <claude|cursor|codex|windsurf>

ClickHouse Cloud で自分のサービスの Connect ダイアログを開き、Connect with MCP を有効にします。次に 両方の エンドポイントを追加し、ブラウザでの OAuth を完了します。

claude mcp add --transport http clickhouse-cloud https://mcp.clickhouse.cloud/mcp
claude mcp add --transport http clickstack https://mcp.clickhouse.cloud/clickstack
claude mcp login clickhouse-cloud
claude mcp login clickstack

codex mcp add clickhouse-cloud --url https://mcp.clickhouse.cloud/mcp
codex mcp add clickstack --url https://mcp.clickhouse.cloud/clickstack
codex mcp login clickhouse-cloud
codex mcp login clickstack

これを一度だけ .cursor/mcp.json に追加し、その後 Cursor の設定で両方のサーバーを認可します。

{
  "mcpServers": {
    "clickhouse-cloud": { "url": "https://mcp.clickhouse.cloud/mcp" },
    "clickstack": { "url": "https://mcp.clickhouse.cloud/clickstack" }
  }
}

これを一度だけ ~/.codeium/windsurf/mcp_config.json に追加し、その後両方のサーバーを認可します。

{
  "mcpServers": {
    "clickhouse-cloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.clickhouse.cloud/mcp"]
    },
    "clickstack": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.clickhouse.cloud/clickstack"]
    }
  }
}

いま ClickHouse への接続を検証します。

Use the clickhouse-cloud MCP to list my databases. Run read-only queries only.

モジュール 05 でテレメトリを送るまで、ClickStack の結果は空で問題ありません。MCP のセットアップを後でやり直さないでください。モジュール 06 と 07 では、ここで設定した clickstack 接続を使います。

ステップ 8 — Langfuse と OpenAI のキーを作成する

Langfuse は、モジュール 08 で使う AI チャットのトレースを記録します。

対面トレーニングの場合: トレーナーから安全な方法で提供される受講者専用の OpenAI プロジェクト API キーを使い、項目 3 はスキップしてください。項目 1 と 2 の Langfuse のキーは必要です。

US Langfuse Cloud または EU Langfuse Cloud でプロジェクトを作成します。
プロジェクト API キーのペアを作成し、public キーと secret キーを保存します。
platform.openai.com/api-keys でプロジェクトスコープの API キーを作成し、課金を有効にします。

プロジェクトを作成したリージョンに対応する Langfuse の URL を使ってください。

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=https://us.cloud.langfuse.com

OPENAI_API_KEY=sk-...

.env.workshop にすでに入っているモデルと API ベースのデフォルト値はそのままにしてください。

ステップ 9 — `.env.workshop` を埋める

ステップ 6 のサービスの値と、ステップ 8 のキーを既存のフィールドにコピーします。

CLICKHOUSE_HOST=<hostname without https:// or port>
CLICKHOUSE_PORT=8443
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=<one-time service password>
CLICKHOUSE_DATABASE=nyc_tlc_data
CLICKHOUSE_SECURE=true

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=https://us.cloud.langfuse.com
OPENAI_API_KEY=sk-...

これらの名前をシェルで export しないでください。export された値は env ファイルを上書きします。

ステップ 10 — preflight を実行してアプリを起動する

以下のコマンドは、クローンしたリポジトリ内のどこからでも正しいディレクトリに移動します。

cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app"
./preflight.sh

最後の行が Overall: READY になってから次に進んでください。表示された対処を適用してスクリプトを再実行します。次にスタックを起動します。

docker compose --env-file .env.workshop -f docker-compose.workshop.yml up -d --build
docker compose --env-file .env.workshop -f docker-compose.workshop.yml ps

約2分以内に、ローカルの backend と frontend のアプリコンテナが healthy を報告し、アプリが localhost:8080 で読み込まれるはずです。ローカルにはデータベースサーバーは起動しません。モジュール 01 まではダッシュボードが空でも正常です。

完了チェック

clickhousectl cloud service get <service-id> がサービスの準備完了を報告する。
clickhouse client ... --query "SELECT version()" が成功する。
エージェントが ClickHouse MCP 経由でデータベースを一覧できる。
アプリディレクトリから実行した ./preflight.sh が Overall: READY で終わる。
Docker のサービスが healthy で、ローカルアプリが読み込まれる。

01 ClickHouse Cloud に進んでください。

成果