00 Thiết lập

Hãy chọn macOS hoặc Windows ở phần header trang trước khi bắt đầu. Lựa chọn của bạn được giữ lại suốt workshop. Windows dùng Ubuntu trên WSL 2 nên cùng những câu lệnh Bash, Docker, ClickHouse, và agent đó đều hoạt động trong mọi module.

Kết quả

Trong khoảng 25 phút, bạn sẽ có:

• một service ClickHouse Cloud và một organization API key;
• clickhousectl và client database clickhouse;
• ClickHouse skills cùng các kết nối ClickHouse và ClickStack MCP trong coding agent của bạn;
• các key Langfuse và OpenAI; và
• ứng dụng chạy khỏe mạnh tại localhost:8080.

ClickHouse, Postgres, ClickPipes, ClickStack/HyperDX, Langfuse, và các endpoint MCP đều được host trên cloud. Chỉ có ứng dụng workshop, các công cụ CLI/client, coding agent, bộ sinh tải, và collector telemetry không trạng thái là chạy trên máy bạn.

Sau Bước 2, hãy chạy mọi câu lệnh từ thư mục ứng dụng trừ khi một bước nói khác.

Bước 1 — Kiểm tra các yêu cầu tiên quyết

Bạn cần Docker với ít nhất 6 GB bộ nhớ, Git, Node.js 22+, Python 3, và một coding agent có hỗ trợ MCP: Claude Code, Cursor, Codex CLI, hoặc Windsurf.

Thiết lập macOS

Cài Docker Desktop for Mac và cấp ít nhất 6 GB trong Settings -> Resources. Mở Terminal và chạy:

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

Chỉ tiếp tục khi mọi câu lệnh đều in ra một phiên bản và docker version hiển thị cả phần Client lẫn Server.

Bước 2 — Clone repo và chuyển sang branch của workshop

Chạy lệnh này trong Terminal của 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

Hãy giữ terminal này ở ClickHouse_Demos/workshops/build_workshop/app. Trên Windows, điều đó nghĩa là terminal Ubuntu. Script preflight là ./preflight.sh bên trong thư mục này. Hãy ở lại build-workshop-v1 trừ trong các bài kiểm thử lỗi ở Module 07. Xác nhận branch ngay bây giờ:

git branch --show-current

Kết quả mong đợi: build-workshop-v1.

Bước 3 — Tạo tài khoản ClickHouse Cloud và API key

Đào tạo trực tiếp: Hãy dùng ClickHouse Cloud organization API key riêng cho học viên do người hướng dẫn cung cấp một cách an toàn và bỏ qua bước này.

1. Đăng nhập hoặc bắt đầu bản dùng thử tại console.clickhouse.cloud.
2. Mở API Keys, tạo một organization key loại Admin, và lưu lại Key ID cùng secret của nó.

Secret chỉ hiển thị một lần. Hãy lưu nó ngoài repository; đừng đặt nó vào .env.workshop.

Bước 4 — Cài clickhousectl

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

Hãy thêm ~/.local/bin vào profile shell của bạn nếu một terminal mới không tìm thấy clickhousectl. Trên Windows, hãy cài và chạy nó bên trong Ubuntu; đừng dùng một file thực thi Windows trong PowerShell.

Bước 5 — Xác thực clickhousectl

Dùng API key từ Bước 3. Dạng lệnh tương tác giữ secret khỏi lịch sử shell:

clickhousectl cloud auth login --interactive

Automation đáng tin cậy có thể dùng dạng tường minh mà CLI mong đợi:

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

Kiểm chứng cả thông tin đăng nhập đã lưu và quyền truy cập Cloud:

clickhousectl cloud auth status
clickhousectl cloud org list

clickhousectl lưu thông tin đăng nhập của project dưới .clickhouse/ trong thư mục hiện tại. Hãy tiếp tục chạy các lệnh Cloud từ thư mục ứng dụng và đừng bao giờ commit hay chia sẻ thư mục đó.

Bước 6 — Tạo service ClickHouse

Hãy chọn region mà bạn cũng sẽ dùng cho Postgres ở Module 03. Thay region ví dụ nếu cần:

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

Hãy lưu lại service ID và password của default user dùng một lần được trả về. Kiểm tra xem service đã sẵn sàng chưa:

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

Hãy cài một client cùng bản phát hành major/minor với service Cloud. Điều này tránh được các cảnh báo unknown-setting mà một client stable mới hơn có thể phát ra khi làm việc với một server Cloud hơi cũ hơn:

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 chỉ cài một binary client; nó không khởi động một server ClickHouse. Mọi truy vấn trong workshop đều nhắm vào ClickHouse Cloud. Từ hộp thoại Connect của service, hãy copy hostname và kiểm chứng client. Cờ --password sẽ hỏi mà không hiện lại 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()"

Kết quả mong đợi: một dòng chứa phiên bản ClickHouse và default.

Bước 7 — Cấu hình agent skills và cả hai MCP server một lần

Các phần tích hợp này có nhiệm vụ riêng biệt:

Trước tiên hãy cài các skill cho agent của bạn:

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

Trong ClickHouse Cloud, hãy mở hộp thoại Connect của service và bật Connect with MCP. Sau đó thêm cả hai endpoint và hoàn tất 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"]
    }
  }
}

Hãy kiểm chứng kết nối ClickHouse ngay bây giờ:

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

Một kết quả ClickStack rỗng là điều bình thường cho tới khi Module 05 gửi telemetry. Đừng lặp lại phần thiết lập MCP về sau; Module 06 và 07 dùng kết nối clickstack đã cấu hình ở đây.

Bước 8 — Tạo các key Langfuse và OpenAI

Langfuse ghi lại các trace AI chat được dùng ở Module 08.

Đào tạo trực tiếp: Hãy dùng OpenAI project API key riêng cho học viên do người hướng dẫn cung cấp một cách an toàn và bỏ qua mục 3. Bạn vẫn cần các key Langfuse từ mục 1 và 2.

1. Tạo một project tại US Langfuse Cloud hoặc EU Langfuse Cloud.
2. Tạo một cặp project API key và lưu lại public key cùng secret key.
3. Tạo một API key theo phạm vi project tại platform.openai.com/api-keys và bật thanh toán.

Hãy dùng URL Langfuse của region mà bạn đã tạo project:

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

OPENAI_API_KEY=sk-...

Hãy giữ nguyên các giá trị mặc định về model và API base đã có trong .env.workshop.

Bước 9 — Điền .env.workshop

Copy các giá trị của service từ Bước 6 và các key từ Bước 8 vào các field có sẵn:

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

Đừng export các tên này trong shell: giá trị đã export sẽ ghi đè file env.

Bước 10 — Chạy preflight và khởi động ứng dụng

Các câu lệnh dưới đây đưa bạn vào đúng thư mục từ bất cứ đâu bên trong repository đã clone:

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

Chỉ tiếp tục khi dòng cuối cùng là Overall: READY. Hãy áp dụng bản sửa được in ra và chạy lại script. Sau đó khởi động stack:

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

Trong khoảng hai phút, các container ứng dụng backend và frontend local sẽ báo healthy và ứng dụng sẽ tải được tại localhost:8080. Không có server database nào được khởi động ở local. Các dashboard rỗng là đúng cho tới Module 01.

Kiểm tra hoàn thành

• clickhousectl cloud service get <service-id> báo service đã sẵn sàng.
• clickhouse client ... --query "SELECT version()" chạy thành công.
• Agent của bạn liệt kê được các database qua ClickHouse MCP.
• ./preflight.sh kết thúc bằng Overall: READY khi chạy từ thư mục ứng dụng.
• Các service Docker đều healthy và ứng dụng local tải được.

Tiếp tục tới 01 ClickHouse Cloud.