00 설치

클라우드 서비스를 만들고, 로컬 클라이언트를 설치하고, 에이전트를 한 번 연결한 뒤 로컬 앱을 시작합니다.

시작하기 전에 페이지 헤더에서 macOS 또는 Windows를 선택하세요. 선택은 워크숍 전체에서 유지됩니다. Windows는 WSL 2의 Ubuntu를 사용하므로 동일한 Bash, Docker, ClickHouse, 에이전트 명령이 모든 모듈에서 동작합니다.

결과물

약 25분 안에 다음을 갖추게 됩니다:

ClickHouse Cloud 서비스와 조직 API 키;
clickhousectl과 clickhouse 데이터베이스 클라이언트;
코딩 에이전트 안의 ClickHouse 스킬과 ClickHouse·ClickStack MCP 연결;
Langfuse와 OpenAI 키; 그리고
localhost:8080에서 정상 동작하는 앱.

ClickHouse, Postgres, ClickPipes, ClickStack/HyperDX, Langfuse, MCP 엔드포인트는 클라우드에서 호스팅됩니다. 여러분의 머신에서 실행되는 것은 워크숍 앱, CLI/클라이언트 도구, 코딩 에이전트, 부하 생성기, 무상태 텔레메트리 컬렉터뿐입니다.

Step 2 이후에는 별도 언급이 없으면 모든 명령을 앱 디렉터리에서 실행하세요.

Step 1 — 사전 요구사항 확인

메모리를 최소 6 GB 할당한 Docker, Git, Node.js 22+, Python 3, 그리고 MCP를 지원하는 코딩 에이전트 하나(Claude Code, Cursor, Codex CLI 또는 Windsurf)가 필요합니다.

macOS 설치

Docker Desktop for Mac을 설치하고 Settings -> Resources에서 최소 6 GB를 할당하세요. 터미널을 열고 실행합니다:

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

모든 명령이 버전을 출력하고 docker version이 Client와 Server 섹션을 모두 보여줄 때만 계속하세요.

회사에서 관리하는 노트북인가요?

회사 정책이 MCP 설치나 브라우저 OAuth를 차단할 수 있습니다. Step 7의 OAuth 단계가 열리지 않으면 개인 머신을 사용하거나 관리자에게 문의하세요.

Step 2 — 저장소를 클론하고 워크숍 브랜치로 전환

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입니다. Module 07의 결함 테스트 중을 제외하면 build-workshop-v1에 머무르세요. 지금 브랜치를 확인하세요:

git branch --show-current

예상 결과: build-workshop-v1.

Step 3 — ClickHouse Cloud 계정과 API 키 만들기

워크숍 당일 이전에: 세 계정을 모두 만드세요

일정이 정해진 워크숍에 참석한다면 ClickHouse Cloud, Langfuse, OpenAI 계정을 미리 만들어 두세요. 각 가입마다 이메일이나 전화 인증을 기다리는 데 5~10분이 걸릴 수 있습니다. 설치 중에 여기로 돌아와 실습에서 사용하는 키와 리소스를 만드세요.

대면 교육: 트레이너가 안전하게 제공한 학습자 전용 ClickHouse Cloud 조직 API 키를 사용하고 이 단계는 건너뛰세요.

console.clickhouse.cloud에서 로그인하거나 트라이얼을 시작하세요.
API Keys를 열고 Admin 조직 키를 만든 뒤, Key ID와 시크릿을 저장하세요.

시크릿은 한 번만 표시됩니다. 저장소 외부에 보관하고 .env.workshop에 넣지 마세요.

Step 4 — `clickhousectl` 설치

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

새 터미널에서 clickhousectl을 찾지 못하면 셸 프로필에 ~/.local/bin을 추가하세요. Windows에서는 Ubuntu 안에서 설치하고 실행하세요. PowerShell에서 Windows 실행 파일을 쓰지 마세요.

Step 5 — `clickhousectl` 인증

Step 3의 API 키를 사용하세요. 대화형 방식은 시크릿을 셸 히스토리에 남기지 않습니다:

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 명령은 계속 앱 디렉터리에서 실행하고, 그 폴더는 절대 커밋하거나 공유하지 마세요.

Step 6 — ClickHouse 서비스 만들기

Module 03에서 Postgres에도 사용할 리전을 선택하세요. 필요하면 예시 리전을 바꾸세요:

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>

Cloud 서비스와 같은 major/minor 릴리스의 클라이언트를 설치하세요. 이렇게 하면 조금 더 오래된 Cloud 서버에 대해 새로운 stable 클라이언트가 낼 수 있는 알 수 없는 설정 경고를 피할 수 있습니다:

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가 담긴 한 행.

Step 7 — 에이전트 스킬과 두 MCP 서버를 한 번에 설정

이 통합들은 각기 다른 역할을 합니다:

통합	목적	사용 위치
ClickHouse 스킬	ClickHouse 관행에 맞춰 스키마와 SQL 검토	모듈 01과 03
ClickHouse MCP (`/mcp`)	`SELECT` 쿼리로 서비스 읽기	모듈 01과 04
ClickStack MCP (`/clickstack`)	텔레메트리 검색과 SRE 산출물 저장	모듈 06과 07

먼저 사용하는 에이전트에 스킬을 설치하세요:

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

ClickHouse Cloud에서 서비스의 Connect 대화상자를 열고 Connect with MCP를 활성화하세요. 그다음 두 엔드포인트를 추가하고 브라우저 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

.cursor/mcp.json에 다음을 한 번 추가한 뒤, Cursor 설정에서 두 서버를 모두 승인하세요:

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

~/.codeium/windsurf/mcp_config.json에 다음을 한 번 추가한 뒤, 두 서버를 모두 승인하세요:

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

Module 05에서 텔레메트리를 보내기 전까지 ClickStack 결과가 비어 있는 것은 정상입니다. MCP 설정을 나중에 다시 하지 마세요. 모듈 06과 07은 여기서 설정한 clickstack 연결을 사용합니다.

Step 8 — Langfuse와 OpenAI 키 만들기

Langfuse는 Module 08에서 사용하는 AI 채팅 트레이스를 기록합니다.

대면 교육: 트레이너가 안전하게 제공한 학습자 전용 OpenAI 프로젝트 API 키를 사용하고 항목 3은 건너뛰세요. 항목 1과 2의 Langfuse 키는 여전히 필요합니다.

US Langfuse Cloud 또는 EU Langfuse Cloud에서 프로젝트를 만드세요.
프로젝트 API 키 쌍을 만들고 public 키와 secret 키를 저장하세요.
platform.openai.com/api-keys에서 프로젝트 범위 API 키를 만들고 결제를 활성화하세요.

프로젝트를 만든 리전에 해당하는 Langfuse URL을 사용하세요:

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

OPENAI_API_KEY=sk-...

.env.workshop에 이미 있는 모델과 API 베이스 기본값은 그대로 두세요.

Step 9 — `.env.workshop` 채우기

Step 6의 서비스 값과 Step 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 파일을 덮어씁니다.

Step 10 — preflight 실행과 앱 시작

아래 명령은 클론한 저장소 안 어디에서든 올바른 디렉터리로 이동합니다:

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

약 2분 안에 로컬 backend와 frontend 앱 컨테이너가 healthy를 보고하고 앱이 localhost:8080에서 로드되어야 합니다. 로컬에서 데이터베이스 서버는 시작되지 않습니다. Module 01까지는 대시보드가 비어 있는 것이 정상입니다.

완료 확인

clickhousectl cloud service get <service-id>가 서비스가 준비되었다고 보고합니다.
clickhouse client ... --query "SELECT version()"이 성공합니다.
에이전트가 ClickHouse MCP를 통해 데이터베이스 목록을 나열합니다.
앱 디렉터리에서 ./preflight.sh가 Overall: READY로 끝납니다.
Docker 서비스가 healthy이고 로컬 앱이 로드됩니다.

01 ClickHouse Cloud로 계속하세요.

결과물