00 Setup

Create the cloud services, install local clients, connect your agent once, and start the local app.

Choose macOS or Windows in the page header before you begin. Your choice persists across the workshop. Windows uses Ubuntu on WSL 2 so the same Bash, Docker, ClickHouse, and agent commands work in every module.

Outcome

In about 25 minutes you will have:

a ClickHouse Cloud service and organization API key;
clickhousectl and the clickhouse database client;
ClickHouse skills plus ClickHouse and ClickStack MCP connections in your coding agent;
Langfuse and OpenAI keys; and
the app healthy at localhost:8080.

ClickHouse, Postgres, ClickPipes, ClickStack/HyperDX, Langfuse, and MCP endpoints are cloud-hosted. Only the workshop app, CLI/client tools, coding agent, load generator, and stateless telemetry collector run on your machine.

After Step 2, run every command from the app directory unless a step says otherwise.

Step 1 — Check prerequisites

You need Docker with at least 6 GB of memory, Git, Node.js 20+, Python 3, and one MCP-capable coding agent: Claude Code, Cursor, Codex CLI, or Windsurf.

macOS setup

Install Docker Desktop for Mac and allocate at least 6 GB in Settings -> Resources. Open Terminal and run:

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

Continue only when every command prints a version and docker version shows both a Client and Server section.

Managed laptop?

Corporate policy can block MCP installation or browser OAuth. Use a personal machine or ask your administrator if the OAuth step in Step 7 cannot open.

Step 2 — Clone the repo and switch to the workshop branch

Run this in macOS Terminal:

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

Keep this terminal in ClickHouse_Demos/workshops/build_workshop/app. On Windows, this means the Ubuntu terminal. The preflight script is ./preflight.sh inside this directory. Stay on build-workshop-v1 except during Module 07 fault tests. Confirm the branch now:

git branch --show-current

Expected: build-workshop-v1.

Step 3 — Create a ClickHouse Cloud account and API key

In-person training: Use the learner-specific ClickHouse Cloud organization API key provided securely by your trainer and skip this step.

Sign in or start a trial at console.clickhouse.cloud.
Open API Keys, create an Admin organization key, and save its Key ID and secret.

The secret is displayed once. Store it outside the repository; do not put it in .env.workshop.

Step 4 — Install `clickhousectl` and ClickHouse client

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

# Installs the stable ClickHouse binary and creates ~/.local/bin/clickhouse.
clickhousectl local use stable
clickhouse client --version

Here local use selects the local client binary version. It does not install or start a ClickHouse server; every query in this workshop targets ClickHouse Cloud.

Add ~/.local/bin to your shell profile if a new terminal cannot find either command. On Windows, both commands are installed inside Ubuntu; do not install or run their Windows executables in PowerShell.

Step 5 — Authenticate `clickhousectl`

Use the API key from Step 3. The interactive form keeps the secret out of shell history:

clickhousectl cloud auth login --interactive

Trusted automation can use the explicit form the CLI expects:

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

Verify both saved credentials and Cloud access:

clickhousectl cloud auth status
clickhousectl cloud org list

clickhousectl stores project credentials under .clickhouse/ in the current directory. Keep running Cloud commands from the app directory and never commit or share that folder.

Step 6 — Create the ClickHouse service

Choose the region you will also use for Postgres in Module 03. Replace the example region if needed:

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

Save the returned service ID and one-time default-user password. Check readiness:

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

From the service Connect dialog, copy the hostname and verify the local client. The --password flag prompts without echoing the password:

clickhouse client \
  --host <your-service-hostname> \
  --secure \
  --user default \
  --password \
  --query "SELECT version(), currentUser()"

Expected: one row containing the ClickHouse version and default.

Step 7 — Configure agent skills and both MCP servers once

These integrations have distinct jobs:

Integration	Purpose	Used in
ClickHouse skills	Review schema and SQL against ClickHouse practices	Modules 01 and 03
ClickHouse MCP (`/mcp`)	Read your service with `SELECT` queries	Modules 01 and 04
ClickStack MCP (`/clickstack`)	Search telemetry and save SRE artifacts	Modules 06 and 07

First install the skills for your agent:

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

In ClickHouse Cloud, open your service's Connect dialog and enable Connect with MCP. Then add both endpoints and complete browser 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

Add this once to .cursor/mcp.json, then authorize both servers in Cursor settings:

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

Add this once to ~/.codeium/windsurf/mcp_config.json, then authorize both servers:

{
  "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"]
    }
  }
}

Verify the ClickHouse connection now:

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

An empty ClickStack result is expected until Module 05 sends telemetry. Do not repeat MCP setup later; Modules 06 and 07 use the clickstack connection configured here.

Step 8 — Create Langfuse and OpenAI keys

Langfuse records the AI chat traces used in Module 08.

In-person training: Use the learner-specific OpenAI project API key provided securely by your trainer and skip item 3. You still need the Langfuse keys from items 1 and 2.

Create a project at US Langfuse Cloud or EU Langfuse Cloud.
Create a project API key pair and save the public and secret keys.
Create a project-scoped API key at platform.openai.com/api-keys and enable billing.

Use the Langfuse URL for the region where you created the project:

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

OPENAI_API_KEY=sk-...

Keep the model and API-base defaults already present in .env.workshop.

Step 9 — Fill `.env.workshop`

Copy the service values from Step 6 and the keys from Step 8 into the existing fields:

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-...

Do not export these names in the shell: exported values override the env file.

Step 10 — Run preflight and start the app

The commands below enter the correct directory from anywhere inside the cloned repository:

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

Continue only when the last line is Overall: READY. Apply any printed fix and rerun the script. Then start the stack:

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

Within about two minutes, the local backend and frontend app containers should report healthy and the app should load at localhost:8080. No database server is started locally. Empty dashboards are correct until Module 01.

Completion check

clickhousectl cloud service get <service-id> reports the service is ready.
clickhouse client ... --query "SELECT version()" succeeds.
Your agent lists databases through the ClickHouse MCP.
./preflight.sh ends with Overall: READY from the app directory.
Docker services are healthy and the local app loads.

Continue to 01 ClickHouse Cloud.

00 Setup

On this page