00 セットアップ

学習者向けレッスン 00 セットアップ に対応するファシリテーター用の手引きです。

タイミング

約25分。待ち時間の発生する手順（サービスの作成、docker compose up）は、オープニングトークの前または最中に開始して、話している間に裏で進むようにしてください。 3つのアカウント登録（ClickHouse Cloud、Langfuse、OpenAI）は当日より前に済ませるよう参加者に促してください。 それぞれ5〜10分かかるため、これでこのモジュールが時間内に収まります。

複数プラットフォームが混在する会場では、WSL 2 と Docker Desktop をまだインストールしていない Windows 学習者のために、セッション前にさらに10分を確保してください。wsl --install の後に再起動が必要になる場合があります。

トレーナーが認証情報を提供する対面セッションの場合:

• 学習者ごとに、一時的な ClickHouse Cloud 組織と OpenAI プロジェクトの API キーを個別に発行してください。 1つのキーを会場全体で共有しては絶対にいけません。
• 各キーは、チャットやスライドではなく、承認されたシークレット共有チャンネルで渡してください。
• OpenAI プロジェクトの予算とレート制限を設定し、セッション中は使用量を監視してください。
• ワークショップ後に両方のキーを失効させてください。いずれかが漏洩した場合は直ちにローテーションします。

トークトラック

• セッションの枠組みを示す: 既存のアプリを ClickHouse Cloud へ移し、構築はエージェントが行う。
• CLI はデフォルトユーザーのパスワードを1度だけ返す。学習者にはすぐ保存させること。 ホスト名はサービスの Connect ダイアログで確認できる。
• モジュール 00 で Cloud サービスを作成し、すべての認証情報を埋めるようになったため、待ち時間の発生する処理は ここに前倒しされている。モジュール 01 は、すでに存在するサービス上でスキーマを構築するだけ。
• ステップ 7 はエージェント統合の唯一のセットアップ: skills、ClickHouse MCP、ClickStack MCP。
• ステップ 1 の前に、学習者にページヘッダーで macOS か Windows を選択させること。Windows では、 PowerShell は WSL のブートストラップ用のみ。ワークショップのコマンドはすべて Ubuntu で実行する。
• WSL 2 はセッション中のインストールではなく、Windows の事前課題として扱うこと。開場前に、 サポートされる Windows ビルド、ローカル管理者権限、仮想化、ホストの 16 GB RAM、20 GB の空きディスク、 Ubuntu のバージョン 2、そして Docker Desktop の Ubuntu 統合を確認しておくこと。

よくある失敗

• 業務用メールアドレスが既存の ClickHouse 組織に紐づいており、トライアルクレジットが表示されない。 個人のメールアドレスに誘導する（事前課題で判明する）。
• 企業ポリシーによりコーディングエージェントが MCP サーバーを追加できない（事前課題のスモークテストで判明する）。
• Docker の割り当てが不足していて docker compose up が失敗する（6 GB 以上が必要）。
• Windows 学習者が /mnt/c 配下にクローンしてしまい、バインドマウントが遅くなったり CRLF で失敗する。 Ubuntu 内の ~/ClickHouse_Demos に再クローンし、git config --global core.autocrlf input を設定する。
• Docker Desktop は動いているが Ubuntu から到達できない。WSL 2 エンジンと Ubuntu の明示的な統合を有効にし、 PowerShell から wsl --shutdown を実行する。
• コマンドは WSL で実行しているのに、コーディングエージェントが別の C:\Users のチェックアウトを開いている。 デスクトップのエージェントで WSL の ~/ClickHouse_Demos フォルダーを開き直し、そのターミナルが uname -s で Linux を返すことを確認する。
• 企業ポリシーが WSL、仮想化、Docker Desktop、または OAuth をブロックしている。これはモジュール中に 解決できない。学習者を準備済みの貸出機か個人のマシンに移す。
• Cloud サービスがアイドルでゼロにスケールした後の最初のリクエストは、かつて 500 を返していた。 現在はバックエンドが接続時にアイドル復帰をリトライするため、最初のダッシュボード読み込みが数秒止まることは あっても成功する。追いかけるべき障害ではない。2026-07 のクリーンルームでのドライランで確認済み。

リセット手順

• トライアルが使えず詰まっている参加者は、貸出用 Cloud サービスのプールに案内する。
• cp .env.workshop.example .env.workshop をやり直して再入力する。.env.workshop が誤ってコミットされて いないことを確認する。
• Windows では wsl --status、wsl --version、wsl --list --verbose を確認する。Ubuntu は バージョン 2 でなければならない。Ubuntu 内では pwd が /home/ で始まり、docker version が Client と Server の両方を表示すること。
• TODO: リセットコマンドを確定する。