00 การติดตั้ง

คู่มือประกอบของผู้ดำเนินเวิร์กช็อปสำหรับบทเรียนผู้เรียน 00 การติดตั้ง

เวลา

ประมาณ 25 นาที เริ่มขั้นตอนแบบสั่งแล้วรอ (สร้าง service, docker compose up) ก่อนหรือระหว่างการบรรยายเปิดงาน เพื่อให้มันทำงานอยู่เบื้องหลัง ผลักดันให้ผู้เข้าร่วม สมัครบัญชีทั้งสาม (ClickHouse Cloud, Langfuse, OpenAI) ก่อนวันงาน แต่ละบัญชีใช้เวลา 5 ถึง 10 นาที เพื่อให้โมดูลนี้อยู่ในงบเวลา

สำหรับห้องที่ใช้หลายแพลตฟอร์ม เผื่อเวลาอีก 10 นาทีก่อนเซสชันให้ผู้เรียนบน Windows ที่ ยังไม่ได้ติดตั้ง WSL 2 และ Docker Desktop อาจต้องรีสตาร์ตเครื่องหลัง wsl --install

สำหรับเซสชันแบบพบหน้าที่ผู้สอนเตรียม credential ให้:

• ออกคีย์ ClickHouse Cloud organization และ OpenAI project API แบบชั่วคราวแยกกันให้ ผู้เรียนแต่ละคน ห้ามใช้คีย์เดียวร่วมกันทั้งห้อง
• ส่งมอบคีย์แต่ละอันผ่านช่องทางแบ่งปันความลับที่ได้รับอนุมัติ ไม่ใช่ผ่าน chat หรือสไลด์
• ตั้งงบประมาณและ rate limit ของ OpenAI project แล้วเฝ้าดูการใช้งานระหว่างเซสชัน
• เพิกถอนคีย์ทั้งสองหลังจบเวิร์กช็อป หมุนคีย์ใดก็ตามทันทีหากถูกเปิดเผย

แนวการบรรยาย

• วางกรอบของเซสชัน: พวกเขาจะย้ายแอปที่มีอยู่ไปบน ClickHouse Cloud และ agent เป็นคนสร้าง
• CLI คืนรหัสผ่านของ default user มาเพียงครั้งเดียว ให้ผู้เรียนบันทึกไว้ทันที หน้าต่าง Connect ของ service จะให้ hostname
• โมดูล 00 ตอนนี้สร้าง Cloud service และกรอก credential ทั้งหมด ดังนั้นงานแบบสั่งแล้วรอ ถูกย้ายมาไว้ข้างหน้าที่นี่ โมดูล 01 แค่สร้าง schema บน service ที่มีอยู่แล้ว
• ขั้นที่ 7 เป็นการตั้งค่าการเชื่อมต่อ agent เพียงจุดเดียว: skills, ClickHouse MCP และ ClickStack MCP
• ให้ผู้เรียนเลือก macOS หรือ Windows ที่ส่วนหัวของหน้าก่อนขั้นที่ 1 บน Windows PowerShell ใช้เพื่อ bootstrap WSL เท่านั้น คำสั่งทุกคำสั่งของเวิร์กช็อปรันใน Ubuntu
• ถือว่า WSL 2 เป็นงานเตรียมล่วงหน้าของ Windows ไม่ใช่การติดตั้งในเซสชัน ยืนยันว่า build ของ Windows รองรับ, มีสิทธิ์ local administrator, เปิด virtualization, host RAM 16 GB, พื้นที่ดิสก์ว่าง 20 GB, Ubuntu เป็นเวอร์ชัน 2 และการเชื่อมต่อ Ubuntu ของ Docker Desktop ก่อนเปิดประตู

ปัญหาที่พบบ่อย

• อีเมลที่ทำงานถูกผูกกับ ClickHouse org ที่มีอยู่แล้ว จึงไม่มีเครดิต trial ปรากฏ ให้ชี้ไปใช้อีเมลส่วนตัว (ตรวจพบในงานเตรียมล่วงหน้า)
• coding agent ไม่สามารถเพิ่ม MCP server ได้เพราะนโยบายองค์กร (ตรวจพบจาก smoke test ในงานเตรียมล่วงหน้า)
• docker compose up ล้มเหลวเพราะจัดสรรทรัพยากรให้ Docker น้อยเกินไป (ต้องมี 6 GB ขึ้นไป)
• ผู้เรียนบน Windows clone ไว้ใต้ /mnt/c ทำให้ bind mount ช้าหรือเกิดปัญหา CRLF ให้ clone ใหม่ ไว้ใต้ ~/ClickHouse_Demos ภายใน Ubuntu และตั้ง git config --global core.autocrlf input
• Docker Desktop ทำงานอยู่แต่ Ubuntu เข้าถึงไม่ได้ ให้เปิด WSL 2 engine และการเชื่อมต่อ Ubuntu แบบระบุชัดเจน แล้วรัน wsl --shutdown จาก PowerShell
• coding agent เปิด checkout แยกใน C:\Users ขณะที่คำสั่งรันใน WSL ให้เปิด โฟลเดอร์ WSL ~/ClickHouse_Demos ใหม่ใน desktop agent และยืนยันว่าเทอร์มินัลของมันรายงานว่าเป็น Linux ด้วย uname -s
• นโยบายองค์กรบล็อก WSL, virtualization, Docker Desktop หรือ OAuth กรณีนี้ซ่อมไม่ได้ ภายในโมดูล ให้ย้ายผู้เรียนไปใช้เครื่องยืมที่เตรียมไว้หรือเครื่องส่วนตัว
• คำขอแรกหลัง Cloud service idle-scale ลงเหลือศูนย์เคยตอบ 500 แต่ตอนนี้ back end จะลองปลุกจาก idle ซ้ำเมื่อเชื่อมต่อ ดังนั้นการโหลด dashboard ครั้งแรกอาจหยุดชะงักไม่กี่วินาที แต่จะสำเร็จ ไม่ใช่ปัญหาที่ต้องตาม ยืนยันแล้วในการซ้อมแบบ clean-room เดือน 2026-07

ขั้นตอนรีเซ็ต

• ชี้ผู้เข้าร่วมที่ติดขัดไปที่ pool ของ Cloud service สำหรับยืมใช้ ถ้า trial ของเขาใช้งานไม่ได้
• รัน cp .env.workshop.example .env.workshop ใหม่แล้วกรอกใหม่ ยืนยันว่าไม่มี .env.workshop หลงเหลือที่ถูก commit ไว้
• บน Windows ให้ตรวจ wsl --status, wsl --version และ wsl --list --verbose โดย Ubuntu ต้องเป็นเวอร์ชัน 2 ภายใน Ubuntu pwd ต้องเริ่มด้วย /home/ และ docker version ต้องแสดง ทั้ง Client และ Server
• TODO: ยืนยันคำสั่งรีเซ็ต