00 การติดตั้ง

เลือก macOS หรือ Windows ที่หัวของหน้าก่อนเริ่ม ตัวเลือกของคุณจะคงอยู่ ตลอดเวิร์กช็อป Windows ใช้ Ubuntu บน WSL 2 เพื่อให้คำสั่ง Bash, Docker, ClickHouse และ agent เดียวกันทำงานได้ในทุกโมดูล

ผลลัพธ์

ในเวลาประมาณ 25 นาที คุณจะมี:

• เซอร์วิส ClickHouse Cloud และคีย์ API ระดับองค์กร
• clickhousectl และไคลเอนต์ฐานข้อมูล clickhouse
• ClickHouse skill พร้อมการเชื่อมต่อ ClickHouse MCP และ ClickStack MCP ใน coding agent ของคุณ
• คีย์ Langfuse และ OpenAI และ
• แอปที่สุขภาพดีที่ localhost:8080

ClickHouse, Postgres, ClickPipes, ClickStack/HyperDX, Langfuse และเอนด์พอยต์ MCP โฮสต์อยู่บนคลาวด์ มีเพียงแอปเวิร์กช็อป เครื่องมือ CLI/ไคลเอนต์ coding agent ตัวสร้างโหลด และตัวเก็บ telemetry แบบไร้สถานะที่รันบนเครื่องของคุณ

หลังขั้นที่ 2 ให้รันทุกคำสั่งจากไดเรกทอรีของแอป เว้นแต่ขั้นตอนจะบอกเป็นอย่างอื่น

ขั้นที่ 1 — ตรวจสอบข้อกำหนดเบื้องต้น

คุณต้องมี Docker ที่มีหน่วยความจำอย่างน้อย 6 GB, Git, Node.js 22+, Python 3 และ coding agent ที่รองรับ MCP หนึ่งตัว: Claude Code, Cursor, Codex CLI หรือ Windsurf

การติดตั้งบน macOS

ติดตั้ง Docker Desktop for Mac และจัดสรรหน่วยความจำอย่างน้อย 6 GB ใน Settings -> Resources เปิด Terminal แล้วรัน:

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

ทำต่อเมื่อทุกคำสั่งพิมพ์เวอร์ชันออกมา และ docker version แสดงทั้งส่วน Client และ Server แล้วเท่านั้น

ขั้นที่ 2 — โคลน repo และสลับไป branch ของเวิร์กช็อป

รันสิ่งนี้ใน 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

ให้เทอร์มินัลนี้อยู่ใน ClickHouse_Demos/workshops/build_workshop/app บน Windows นี่ หมายถึงเทอร์มินัล Ubuntu สคริปต์ preflight คือ ./preflight.sh ภายในไดเรกทอรีนี้ อยู่บน build-workshop-v1 ต่อไปยกเว้นระหว่าง การทดสอบความผิดพลาดในโมดูล 07 ยืนยัน branch ตอนนี้:

git branch --show-current

คาดหวัง: build-workshop-v1

ขั้นที่ 3 — สร้างบัญชี ClickHouse Cloud และคีย์ API

การอบรมแบบพบตัว: ใช้คีย์ API ระดับองค์กรของ ClickHouse Cloud เฉพาะสำหรับผู้เรียน ที่ผู้สอนของคุณให้มาอย่างปลอดภัย และข้ามขั้นตอนนี้

1. ลงชื่อเข้าใช้หรือเริ่มทดลองใช้ที่ console.clickhouse.cloud
2. เปิด API Keys สร้างคีย์องค์กรระดับ Admin และบันทึก Key ID กับ secret ของมัน

secret จะแสดงเพียงครั้งเดียว เก็บไว้นอก repository ห้ามใส่ไว้ใน .env.workshop

ขั้นที่ 4 — ติดตั้ง clickhousectl

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

เพิ่ม ~/.local/bin เข้าไปใน shell profile ของคุณถ้าเทอร์มินัลใหม่หา clickhousectl ไม่เจอ บน Windows ให้ติดตั้งและรันภายใน Ubuntu ห้ามใช้ไฟล์ปฏิบัติการของ Windows ใน PowerShell

ขั้นที่ 5 — ยืนยันตัวตนกับ clickhousectl

ใช้คีย์ API จากขั้นที่ 3 ฟอร์มแบบโต้ตอบช่วยกัน secret ออกจากประวัติเชลล์:

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 จากไดเรกทอรีของแอปต่อไป และห้าม commit หรือแชร์โฟลเดอร์นั้น

ขั้นที่ 6 — สร้างเซอร์วิส ClickHouse

เลือกภูมิภาคที่คุณจะใช้กับ Postgres ในโมดูล 03 ด้วย เปลี่ยนภูมิภาคตัวอย่าง ถ้าจำเป็น:

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 user แบบใช้ครั้งเดียวที่ได้กลับมา ตรวจความพร้อม:

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

ติดตั้งไคลเอนต์จากรุ่น major/minor เดียวกับเซอร์วิส Cloud วิธีนี้เลี่ยง คำเตือน unknown-setting ที่ไคลเอนต์ stable ที่ใหม่กว่าอาจปล่อยออกมาเมื่อคุยกับเซิร์ฟเวอร์ Cloud ที่เก่ากว่าเล็กน้อย:

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

ขั้นที่ 7 — ตั้งค่า agent skill และเซิร์ฟเวอร์ MCP ทั้งสองตัวครั้งเดียว

การผสานเหล่านี้มีหน้าที่ต่างกัน:

ก่อนอื่นติดตั้ง skill สำหรับ agent ของคุณ:

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

ใน ClickHouse Cloud เปิดไดอะล็อก Connect ของเซอร์วิสคุณและเปิดใช้ Connect with MCP แล้วเพิ่มเอนด์พอยต์ ทั้งสอง และทำ 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

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

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

ผลลัพธ์ ClickStack ที่ว่างเปล่าเป็นเรื่องปกติจนกว่าโมดูล 05 จะส่ง telemetry ห้ามทำการตั้งค่า MCP ซ้ำภายหลัง โมดูล 06 และ 07 ใช้การเชื่อมต่อ clickstack ที่ตั้งค่าไว้ที่นี่

ขั้นที่ 8 — สร้างคีย์ Langfuse และ OpenAI

Langfuse บันทึก trace ของแชท AI ที่ใช้ในโมดูล 08

การอบรมแบบพบตัว: ใช้คีย์ API ระดับโปรเจกต์ของ OpenAI เฉพาะสำหรับผู้เรียนที่ผู้สอนของคุณ ให้มาอย่างปลอดภัย และข้ามข้อ 3 คุณยังต้องมีคีย์ Langfuse จากข้อ 1 และ 2

1. สร้างโปรเจกต์ที่ US Langfuse Cloud หรือ EU Langfuse Cloud
2. สร้างคู่คีย์ API ของโปรเจกต์และบันทึก public key กับ secret key
3. สร้างคีย์ API ที่จำกัดขอบเขตของโปรเจกต์ที่ platform.openai.com/api-keys และเปิดใช้การเรียกเก็บเงิน

ใช้ URL ของ Langfuse ตามภูมิภาคที่คุณสร้างโปรเจกต์:

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

OPENAI_API_KEY=sk-...

คงค่าเริ่มต้นของโมเดลและ API base ที่มีอยู่แล้วใน .env.workshop ไว้

ขั้นที่ 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 และเริ่มแอป

คำสั่งด้านล่างเข้าไดเรกทอรีที่ถูกต้องจากที่ไหนก็ได้ภายใน repository ที่โคลนมา:

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

ภายในประมาณสองนาที คอนเทนเนอร์แอป backend และ frontend ในเครื่องควรรายงาน healthy และแอปควรโหลดได้ที่ localhost:8080 ไม่มีเซิร์ฟเวอร์ ฐานข้อมูลถูกเริ่มในเครื่อง แดชบอร์ดว่างเปล่าเป็นเรื่องถูกต้องจนถึงโมดูล 01

การตรวจสอบความสมบูรณ์

• clickhousectl cloud service get <service-id> รายงานว่าเซอร์วิสพร้อมแล้ว
• clickhouse client ... --query "SELECT version()" สำเร็จ
• agent ของคุณแสดงรายการฐานข้อมูลผ่าน ClickHouse MCP
• ./preflight.sh จบด้วย Overall: READY จากไดเรกทอรีของแอป
• เซอร์วิส Docker สุขภาพดีและแอปในเครื่องโหลดได้

ไปต่อที่ 01 ClickHouse Cloud