00 Cài đặt

Tài liệu đồng hành của người điều phối cho bài học 00 Cài đặt.

Thời lượng

Khoảng 25 phút. Hãy khởi động các bước khởi chạy rồi chờ (tạo service, docker compose up) trước hoặc trong lúc dẫn phần mở đầu để chúng chạy song song bên dưới. Hãy thúc học viên hoàn tất ba lần đăng ký tài khoản (ClickHouse Cloud, Langfuse, OpenAI) trước ngày học - mỗi lần mất 5 đến 10 phút - để module này không vượt ngân sách thời gian.

Với các phòng học hỗn hợp nền tảng, hãy dự trù thêm 10 phút trước phiên cho các học viên Windows chưa cài WSL 2 và Docker Desktop. Có thể cần khởi động lại máy sau wsl --install.

Với các phiên trực tiếp dùng thông tin đăng nhập do người hướng dẫn cấp:

• Cấp riêng cho từng học viên các khoá API tạm thời của tổ chức ClickHouse Cloud và của project OpenAI. Tuyệt đối không dùng chung một khoá cho cả phòng.
• Gửi từng khoá qua một kênh chia sẻ bí mật đã được phê duyệt, không qua chat hay slide.
• Áp dụng ngân sách project OpenAI và giới hạn tốc độ, rồi theo dõi mức sử dụng trong phiên.
• Thu hồi cả hai khoá sau workshop. Xoay khoá ngay lập tức nếu khoá nào bị lộ.

Nội dung dẫn giảng

• Định hình phiên học: họ sẽ chuyển một ứng dụng có sẵn sang ClickHouse Cloud, và agent là bên làm phần xây dựng.
• CLI trả về mật khẩu của default user đúng một lần; hãy để học viên lưu lại ngay. Hộp thoại Connect của service cung cấp hostname.
• Module 00 giờ tạo luôn Cloud service và điền đầy đủ mọi thông tin đăng nhập, nên phần khởi chạy rồi chờ được dồn về đây; module 01 chỉ việc tạo schema trên service đã tồn tại sẵn.
• Bước 7 là phần thiết lập tích hợp agent duy nhất: skills, ClickHouse MCP và ClickStack MCP.
• Hãy để học viên chọn macOS hoặc Windows ở phần đầu trang trước Bước 1. Trên Windows, PowerShell chỉ dùng để bootstrap WSL; mọi lệnh của workshop đều chạy trong Ubuntu.
• Hãy coi WSL 2 là phần chuẩn bị trước của Windows, không phải việc cài đặt trong phiên. Xác nhận bản Windows được hỗ trợ, quyền quản trị viên cục bộ, ảo hoá, 16 GB RAM máy chủ, 20 GB đĩa trống, Ubuntu phiên bản 2, và tích hợp Ubuntu của Docker Desktop trước khi mở cửa.

Lỗi thường gặp

• Email công ty đã gắn với một tổ chức ClickHouse có sẵn, nên không thấy credit trial nào. Hãy hướng sang email cá nhân (đã nêu ở phần chuẩn bị trước).
• Coding agent không thêm được MCP server do chính sách của công ty (được phát hiện qua bài smoke test ở phần chuẩn bị trước).
• docker compose up thất bại vì Docker được cấp phát quá ít tài nguyên (cần từ 6 GB trở lên).
• Học viên Windows clone vào dưới /mnt/c, gây bind mount chậm hoặc lỗi CRLF. Hãy clone lại vào ~/ClickHouse_Demos bên trong Ubuntu và đặt git config --global core.autocrlf input.
• Docker Desktop đang chạy nhưng Ubuntu không kết nối được. Hãy bật WSL 2 engine và bật tích hợp Ubuntu một cách tường minh, rồi chạy wsl --shutdown từ PowerShell.
• Coding agent mở một checkout riêng ở C:\Users trong khi các lệnh lại chạy trong WSL. Hãy mở lại thư mục WSL ~/ClickHouse_Demos trong agent trên desktop và xác nhận terminal của nó báo Linux khi chạy uname -s.
• Chính sách công ty chặn WSL, ảo hoá, Docker Desktop hoặc OAuth. Không thể khắc phục trong lúc học module này; hãy chuyển học viên sang máy cho mượn đã chuẩn bị sẵn hoặc máy cá nhân.
• Yêu cầu đầu tiên sau khi một Cloud service tự co giãn về không trước đây trả về 500; back end giờ thử lại việc đánh thức khi kết nối, nên lần tải dashboard đầu tiên có thể dừng vài giây nhưng vẫn thành công. Đây không phải lỗi cần truy đuổi. Đã xác nhận trong buổi tổng duyệt phòng sạch 2026-07.

Các bước khôi phục

• Chỉ người đang bị tắc sang pool Cloud service cho mượn nếu bản trial của họ không dùng được.
• Chạy lại cp .env.workshop.example .env.workshop rồi điền lại; xác nhận không có .env.workshop nào bị commit lạc.
• Trên Windows, kiểm tra wsl --status, wsl --version và wsl --list --verbose; Ubuntu phải ở phiên bản 2. Bên trong Ubuntu, pwd phải bắt đầu bằng /home/ và docker version hiện cả Client và Server.
• TODO: xác nhận các lệnh khôi phục.