00 Setup

Buat layanan cloud, pasang klien lokal, hubungkan agent Anda sekali, dan jalankan aplikasi lokal.

Pilih macOS atau Windows di header halaman sebelum Anda mulai. Pilihan Anda bertahan sepanjang workshop. Windows memakai Ubuntu di WSL 2 sehingga perintah Bash, Docker, ClickHouse, dan agent yang sama bekerja di setiap modul.

Hasil

Dalam sekitar 25 menit Anda akan punya:

sebuah layanan ClickHouse Cloud dan kunci API organisasi;
clickhousectl dan klien database clickhouse;
keahlian ClickHouse ditambah koneksi MCP ClickHouse dan ClickStack di coding agent Anda;
kunci Langfuse dan OpenAI; serta
aplikasi yang sehat di localhost:8080.

ClickHouse, Postgres, ClickPipes, ClickStack/HyperDX, Langfuse, dan endpoint MCP dihosting di cloud. Hanya aplikasi workshop, alat CLI/klien, coding agent, load generator, dan collector telemetri yang stateless yang berjalan di mesin Anda.

Setelah Langkah 2, jalankan setiap perintah dari direktori aplikasi kecuali jika sebuah langkah menyatakan lain.

Langkah 1 — Periksa prasyarat

Anda memerlukan Docker dengan memori minimal 6 GB, Git, Node.js 22+, Python 3, dan satu coding agent yang mendukung MCP: Claude Code, Cursor, Codex CLI, atau Windsurf.

Setup macOS

Pasang Docker Desktop for Mac dan alokasikan minimal 6 GB di Settings -> Resources. Buka Terminal dan jalankan:

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

Lanjutkan hanya jika setiap perintah mencetak versi dan docker version menampilkan bagian Client maupun Server.

Laptop yang dikelola perusahaan?

Kebijakan korporat dapat memblokir pemasangan MCP atau OAuth browser. Gunakan mesin pribadi atau tanyakan kepada administrator Anda jika langkah OAuth di Langkah 7 tidak dapat terbuka.

Langkah 2 — Clone repo dan pindah ke branch workshop

Jalankan ini di Terminal 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

Biarkan terminal ini berada di ClickHouse_Demos/workshops/build_workshop/app. Di Windows, ini berarti terminal Ubuntu. Skrip preflight adalah ./preflight.sh di dalam direktori ini. Tetap di build-workshop-v1 kecuali selama pengujian fault Modul 07. Konfirmasi branch-nya sekarang:

git branch --show-current

Diharapkan: build-workshop-v1.

Langkah 3 — Buat akun ClickHouse Cloud dan kunci API

Sebelum hari workshop: buat ketiga akun

Jika Anda menghadiri workshop terjadwal, buat akun ClickHouse Cloud, Langfuse, dan OpenAI Anda lebih dahulu. Setiap pendaftaran bisa memakan 5–10 menit menunggu verifikasi email atau telepon. Kembali ke sini saat setup untuk membuat kunci dan sumber daya yang dipakai oleh latihan-latihannya.

Pelatihan tatap muka: Gunakan kunci API organisasi ClickHouse Cloud khusus learner yang diberikan secara aman oleh pelatih Anda dan lewati langkah ini.

Masuk atau mulai trial di console.clickhouse.cloud.
Buka API Keys, buat kunci organisasi Admin, dan simpan Key ID beserta secret-nya.

Secret ditampilkan sekali saja. Simpan di luar repositori; jangan menaruhnya di .env.workshop.

Langkah 4 — Pasang `clickhousectl`

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

Tambahkan ~/.local/bin ke profil shell Anda jika terminal baru tidak dapat menemukan clickhousectl. Di Windows, pasang dan jalankan di dalam Ubuntu; jangan memakai executable Windows di PowerShell.

Langkah 5 — Autentikasi `clickhousectl`

Gunakan kunci API dari Langkah 3. Bentuk interaktifnya menjaga secret tidak masuk riwayat shell:

clickhousectl cloud auth login --interactive

Otomasi terpercaya dapat memakai bentuk eksplisit yang diharapkan CLI:

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

Verifikasi kredensial yang tersimpan sekaligus akses Cloud:

clickhousectl cloud auth status
clickhousectl cloud org list

clickhousectl menyimpan kredensial proyek di bawah .clickhouse/ pada direktori saat ini. Terus jalankan perintah Cloud dari direktori aplikasi dan jangan pernah meng-commit atau membagikan folder itu.

Langkah 6 — Buat layanan ClickHouse

Pilih region yang juga akan Anda pakai untuk Postgres di Modul 03. Ganti region contohnya jika perlu:

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

Simpan service ID dan kata sandi default-user sekali-pakai yang dikembalikan. Periksa kesiapannya:

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

Pasang klien dari rilis major/minor yang sama dengan layanan Cloud. Ini menghindari peringatan unknown-setting yang bisa dipancarkan klien stable yang lebih baru terhadap server Cloud yang sedikit lebih tua:

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 hanya memasang biner klien; ia tidak menjalankan server ClickHouse. Setiap kueri workshop menyasar ClickHouse Cloud. Dari dialog Connect layanan, salin hostname-nya dan verifikasi klien. Flag --password akan meminta masukan tanpa menampilkan kata sandi:

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()"

Diharapkan: satu baris berisi versi ClickHouse dan default.

Langkah 7 — Konfigurasikan keahlian agent dan kedua server MCP sekali saja

Integrasi ini punya tugas yang berbeda:

Integrasi	Tujuan	Dipakai di
Keahlian ClickHouse	Meninjau skema dan SQL terhadap praktik ClickHouse	Modul 01 dan 03
ClickHouse MCP (`/mcp`)	Membaca layanan Anda dengan kueri `SELECT`	Modul 01 dan 04
ClickStack MCP (`/clickstack`)	Mencari telemetri dan menyimpan artefak SRE	Modul 06 dan 07

Pertama pasang keahlian untuk agent Anda:

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

Di ClickHouse Cloud, buka dialog Connect layanan Anda dan aktifkan Connect with MCP. Lalu tambahkan kedua endpoint dan selesaikan OAuth browser:

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

Tambahkan ini sekali ke .cursor/mcp.json, lalu otorisasi kedua server di pengaturan Cursor:

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

Tambahkan ini sekali ke ~/.codeium/windsurf/mcp_config.json, lalu otorisasi kedua server:

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

Verifikasi koneksi ClickHouse sekarang:

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

Hasil ClickStack yang kosong adalah hal yang diharapkan sampai Modul 05 mengirim telemetri. Jangan mengulangi setup MCP nanti; Modul 06 dan 07 memakai koneksi clickstack yang dikonfigurasi di sini.

Langkah 8 — Buat kunci Langfuse dan OpenAI

Langfuse mencatat trace chat AI yang dipakai di Modul 08.

Pelatihan tatap muka: Gunakan kunci API proyek OpenAI khusus learner yang diberikan secara aman oleh pelatih Anda dan lewati butir 3. Anda masih memerlukan kunci Langfuse dari butir 1 dan 2.

Buat proyek di US Langfuse Cloud atau EU Langfuse Cloud.
Buat sepasang kunci API proyek dan simpan kunci public serta secret-nya.
Buat kunci API bercakupan proyek di platform.openai.com/api-keys dan aktifkan penagihan.

Gunakan URL Langfuse untuk region tempat Anda membuat proyek:

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

OPENAI_API_KEY=sk-...

Pertahankan nilai default model dan API-base yang sudah ada di .env.workshop.

Langkah 9 — Isi `.env.workshop`

Salin nilai layanan dari Langkah 6 dan kunci dari Langkah 8 ke kolom yang sudah ada:

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

Jangan meng-export nama-nama ini di shell: nilai yang di-export menimpa berkas env.

Langkah 10 — Jalankan preflight dan mulai aplikasi

Perintah di bawah masuk ke direktori yang benar dari mana pun di dalam repositori yang di-clone:

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

Lanjutkan hanya jika baris terakhirnya Overall: READY. Terapkan perbaikan apa pun yang dicetak dan jalankan ulang skripnya. Lalu jalankan tumpukannya:

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

Dalam sekitar dua menit, kontainer aplikasi backend dan frontend lokal seharusnya melaporkan healthy dan aplikasi seharusnya termuat di localhost:8080. Tidak ada server database yang dijalankan secara lokal. Dashboard yang kosong adalah hal yang benar sampai Modul 01.

Pemeriksaan penyelesaian

clickhousectl cloud service get <service-id> melaporkan layanan sudah siap.
clickhouse client ... --query "SELECT version()" berhasil.
Agent Anda mendaftar database melalui ClickHouse MCP.
./preflight.sh diakhiri dengan Overall: READY dari direktori aplikasi.
Layanan Docker sehat dan aplikasi lokal termuat.

Lanjutkan ke 01 ClickHouse Cloud.