00 셋업

학습자 레슨 00 셋업에 대응하는 진행자용 안내서입니다.

타이밍

약 25분. 실행 후 대기하는 단계(서비스 생성, docker compose up)는 오프닝 토크 전이나 진행 중에 착수해서 토크가 진행되는 동안 함께 돌아가게 하세요. 세 가지 계정 가입(ClickHouse Cloud, Langfuse, OpenAI)은 참가자들이 당일 전에 마치도록 독려하세요 — 각각 5~10분이 걸립니다 — 그래야 이 모듈이 배정 시간 안에 들어갑니다.

여러 플랫폼이 섞인 강의실에서는 WSL 2와 Docker Desktop을 아직 설치하지 않은 Windows 학습자를 위해 세션 전에 10분을 더 확보하세요. wsl --install 이후 재시작이 필요할 수 있습니다.

강사가 자격 증명을 제공하는 오프라인 세션의 경우:

• 각 학습자에게 별도의 임시 ClickHouse Cloud 조직 API 키와 OpenAI 프로젝트 API 키를 발급하세요. 하나의 키를 강의실 전체가 공유하는 일은 절대 없어야 합니다.
• 각 키는 채팅이나 슬라이드가 아니라 승인된 비밀 공유 채널로 전달하세요.
• OpenAI 프로젝트 예산과 요청 한도를 적용하고, 세션 중 사용량을 모니터링하세요.
• 워크숍이 끝나면 두 키를 모두 폐기하세요. 어느 쪽이든 노출되면 즉시 교체하세요.

토크 트랙

• 세션의 틀을 잡아주세요: 참가자들은 기존 앱을 ClickHouse Cloud로 옮기게 되며, 실제로 만드는 일은 에이전트가 합니다.
• CLI는 default 사용자 비밀번호를 한 번만 반환합니다. 학습자가 바로 저장하게 하세요. 호스트명은 서비스의 Connect 대화상자에서 제공됩니다.
• 모듈 00에서 이제 Cloud 서비스를 생성하고 모든 자격 증명을 채우므로 실행 후 대기하는 작업이 여기 앞부분에 몰려 있습니다. 모듈 01은 이미 존재하는 서비스 위에 스키마만 만듭니다.
• 7단계는 에이전트 통합을 설정하는 유일한 단계입니다: 스킬, ClickHouse MCP, ClickStack MCP.
• 1단계 전에 학습자가 페이지 헤더에서 macOS나 Windows를 선택하게 하세요. Windows에서 PowerShell은 WSL 부트스트랩용일 뿐이며, 모든 워크숍 명령은 Ubuntu에서 실행됩니다.
• WSL 2는 세션 중 설치가 아니라 Windows 사전 작업으로 취급하세요. 문을 열기 전에 지원되는 Windows 빌드, 로컬 관리자 권한, 가상화, 호스트 RAM 16 GB, 여유 디스크 20 GB, Ubuntu 버전 2, Docker Desktop의 Ubuntu 통합을 확인하세요.

흔한 실패 사례

• 업무용 이메일이 이미 기존 ClickHouse 조직에 연결되어 있어 트라이얼 크레딧이 나타나지 않음. 개인 이메일로 유도하세요(사전 작업에서 드러남).
• 회사 정책 때문에 코딩 에이전트가 MCP 서버를 추가할 수 없음(사전 작업 스모크 테스트에서 드러남).
• Docker에 할당된 자원이 부족해 docker compose up이 실패(6 GB 이상 필요).
• Windows 학습자가 /mnt/c 아래에 클론해서 바인드 마운트가 느리거나 CRLF 오류가 발생. Ubuntu 안의 ~/ClickHouse_Demos에 다시 클론하고 git config --global core.autocrlf input을 설정하세요.
• Docker Desktop은 실행 중인데 Ubuntu에서 접근할 수 없음. WSL 2 엔진과 명시적인 Ubuntu 통합을 활성화하고, PowerShell에서 wsl --shutdown을 실행하세요.
• 명령은 WSL에서 실행되는데 코딩 에이전트가 별도의 C:\Users 체크아웃을 여는 경우. 데스크톱 에이전트에서 ~/ClickHouse_Demos WSL 폴더를 다시 열고, 에이전트의 터미널이 uname -s로 Linux를 보고하는지 확인하세요.
• 회사 정책이 WSL, 가상화, Docker Desktop, OAuth를 차단하는 경우. 모듈 진행 중에는 해결할 수 없습니다. 학습자를 미리 준비한 대여 장비나 개인 장비로 옮기세요.
• Cloud 서비스가 유휴 상태로 0까지 축소된 뒤 첫 요청이 예전에는 500을 반환했습니다. 이제 백엔드가 연결 시 유휴 상태 깨우기를 재시도하므로, 첫 대시보드 로딩이 몇 초 멈출 수 있지만 성공합니다. 추적할 필요 없는 문제입니다. 2026-07 클린룸 리허설에서 확인됨.

초기화 절차

• 트라이얼을 쓸 수 없는 참가자는 대여용 Cloud 서비스 풀로 안내하세요.
• cp .env.workshop.example .env.workshop을 다시 실행하고 값을 다시 채우세요. 커밋된 .env.workshop이 남아 있지 않은지 확인하세요.
• Windows에서는 wsl --status, wsl --version, wsl --list --verbose를 확인하세요. Ubuntu는 버전 2여야 합니다. Ubuntu 안에서 pwd는 /home/으로 시작하고 docker version은 Client와 Server를 모두 보여줘야 합니다.
• TODO: 초기화 명령을 확정.