00 Setup

Facilitator companion to the learner lesson 00 Setup.

Timing

About 25 minutes. Kick off the fire-and-wait steps (create the service, docker compose up) before or during the opening talk so they run underneath it. Push attendees to do the three account signups (ClickHouse Cloud, Langfuse, OpenAI) before the day - each is 5 to 10 minutes - so this module stays inside budget.

For mixed rooms, budget another 10 minutes before the session for Windows learners who have not yet installed WSL 2 and Docker Desktop. A restart can be required after wsl --install.

For in-person sessions with trainer-provided credentials:

• Issue separate temporary ClickHouse Cloud organization and OpenAI project API keys to each learner. Never share one key across the room.
• Deliver each key through an approved secret-sharing channel, not chat or slides.
• Apply an OpenAI project budget and rate limits, then monitor usage during the session.
• Revoke both keys after the workshop. Rotate either key immediately if it is exposed.

Talk track

• Frame the session: they will move an existing app onto ClickHouse Cloud, and the agent does the building.
• The CLI returns the default-user password once; have learners save it immediately. The service Connect dialog provides the hostname.
• Module 00 now creates the Cloud service and fills every credential, so the fire-and-wait is front-loaded here; module 01 just builds the schema on the service that already exists.
• Step 7 is the only agent-integration setup: skills, ClickHouse MCP, and ClickStack MCP.
• Have learners select macOS or Windows in the page header before Step 1. On Windows, PowerShell is only for WSL bootstrap; every workshop command runs in Ubuntu.
• Treat WSL 2 as Windows prework, not an in-session install. Confirm a supported Windows build, local administrator rights, virtualization, 16 GB host RAM, 20 GB free disk, Ubuntu version 2, and Docker Desktop's Ubuntu integration before doors open.

Common failures

• Work email already attached to an existing ClickHouse org, so no trial credits appear. Steer to a personal email (surfaced in prework).
• Coding agent cannot add MCP servers due to corporate policy (surfaced by the prework smoke test).
• docker compose up fails because Docker is under-allocated (needs 6 GB+).
• Windows learner cloned under /mnt/c, causing slow bind mounts or CRLF failures. Re-clone under ~/ClickHouse_Demos inside Ubuntu and set git config --global core.autocrlf input.
• Docker Desktop runs but Ubuntu cannot reach it. Enable the WSL 2 engine and the explicit Ubuntu integration, then run wsl --shutdown from PowerShell.
• The coding agent opens a separate C:\Users checkout while commands run in WSL. Reopen the ~/ClickHouse_Demos WSL folder in the desktop agent and confirm its terminal reports Linux with uname -s.
• Corporate policy blocks WSL, virtualization, Docker Desktop, or OAuth. This cannot be repaired during the module; move the learner to a prepared loaner or personal machine.
• The first request after a Cloud service idle-scales to zero used to 500; the back end now retries the idle-wake on connect, so the first dashboard load may pause a few seconds but succeeds. Not a failure to chase. Confirmed in the 2026-07 clean-room dry run.

Reset steps

• Point a stuck attendee at the loaner Cloud service pool if their trial is unusable.
• Re-run cp .env.workshop.example .env.workshop and re-fill; confirm no stray committed .env.workshop.
• On Windows, verify wsl --status, wsl --version, and wsl --list --verbose; Ubuntu must be version 2. Inside Ubuntu, pwd starts with /home/ and docker version shows both Client and Server.
• TODO: confirm reset commands.