메인 콘텐츠로 건너뛰기
Docker Compose로 로컬에서 전체 에이전트형 데이터 스택을 실행하면 첫 로그인 직후부터 데이터에 관해 질문할 수 있습니다. docker compose up 명령 한 번으로 LibreChat, ClickHouse MCP 서버, ClickHouse, 그리고 관측성을 위한 Langfuse를 모두 실행할 수 있습니다.

​
사전 요구 사항

  • Compose 플러그인(Compose v2 이상)이 포함된 Docker.
  • 리포지토리를 클론하기 위한 Git.
  • 모델 제공업체 API Key(OpenAI, Anthropic 또는 Google 등). 에이전트가 질문에 답하려면 모델이 필요하므로 설정 중에 키를 제공하거나 첫 번째 채팅 전에 LibreChat UI에서 추가하십시오.

​
스택 실행하기

1

리포지토리 복제

git clone https://github.com/ClickHouse/agentic-data-stack
cd agentic-data-stack
이 리포지토리에는 최상위 docker-compose.yml이 포함되어 있으므로, 명령 하나로 전체 스택을 실행할 수 있습니다. 전체 서비스 목록은 아키텍처를 참조하십시오.
2

데모 Setup 스크립트 실행

./scripts/prepare-demo.sh
이 스크립트는 각 서비스의 자격 증명이 포함된 .env 파일을 생성한 다음, 선택한 provider의 API Key를 구성할 수 있는 대화형 메뉴를 표시합니다. 이 키는 .env 파일에 직접 설정할 수도 있습니다. 건너뛴 provider는 모두 user_provided로 유지되므로, 대신 LibreChat UI에서 직접 키를 추가할 수 있습니다.처음 시작할 때 스택은 .env를 기반으로 관리자 사용자를 생성합니다. 기본 로그인 정보는 admin@admin.com / password입니다.
prepare-demo.sh를 실행하기 전에 다음 변수를 지정해 generate-env.sh를 실행하십시오:
USER_EMAIL="you@example.com" USER_PASSWORD="supersecret" USER_NAME="YourName" ./scripts/generate-env.sh
그러면 prepare-demo.sh는 기존 .env를 감지하고 바로 API Key 구성으로 이동합니다.
3

백그라운드에서 서비스 시작

docker compose up -d
시작 순서는 자동으로 처리됩니다. LibreChat은 MCP 서버가 정상 상태가 된 뒤에만 시작되므로, 처음 열 때부터 ClickHouse 연결이 준비되어 있습니다.
4

LibreChat 열기 및 로그인

스택이 실행되면 브라우저에서 다음 서비스에 접속할 수 있습니다:.env 파일의 관리자 자격 증명을 사용해 LibreChat에 로그인하십시오.
5

모델 선택

기본적으로 모델이 선택되어 있습니다. 변경하려면 모델 셀렉터를 열고 사용할 모델을 선택하십시오.Setup 중에 provider 키를 설정하지 않았다면 UI에서 추가하십시오.
모델 셀렉터를 열고 provider 옆의 Set API Key를 클릭하십시오.대화 상자에 키를 붙여넣고 Submit을 클릭하십시오. 만료 시간을 설정하거나, 키가 만료되지 않도록 유지할 수 있습니다.
6

MCP 서버 선택

이 스택은 LibreChat의 librechat.yaml에 MCP 서버를 미리 구성해 둡니다. 메시지 컴포저에서 MCP Servers를 클릭하고 ClickHouse-Local을 선택하십시오.ClickHouse Cloud 서비스를 사용하려면 ClickHouse-Cloud를 대신 선택하십시오.
7

첫 번째 질문하기

예를 들면 다음과 같습니다:
사용 가능한 데이터베이스와 테이블은 무엇이며, 가장 큰 테이블에는 몇 개의 행이 있습니까?
에이전트는 MCP 서버의 도구를 사용해 데이터베이스와 테이블을 나열하고, ClickHouse에 읽기 전용 쿼리를 실행한 뒤, 결과를 바탕으로 답변을 구성합니다. SQL을 직접 작성할 필요는 없습니다.

​
스택 중지 또는 재설정

삭제하지 않고 서비스를 중지합니다: 
docker compose down
모든 컨테이너를 종료하고 깨끗한 상태에서 다시 시작할 수 있도록 모든 볼륨을 삭제하려면 stack 재설정 스크립트를 사용하십시오: 
./scripts/reset-all.sh

​
아키텍처

docker-compose.yml은 4개의 Compose 파일을 포함하는 간단한 엔트리포인트입니다:
Compose file정의 내용
langfuse-compose.ymlLangfuse 및 관련 서비스(ClickHouse, PostgreSQL, Redis, MinIO)
clickhouse-mcp-compose.ymlClickHouse MCP 서버
librechat-compose.ymlLibreChat 및 관련 서비스(MongoDB, Meilisearch, pgvector, RAG API)
admin-panel-compose.ymlLibreChat 관리자 패널
단일 명령으로 시작할 수 있는 이유는 다음 두 가지입니다:
  • 헬스 체크와 시작 순서. Compose는 헬스 체크를 사용해 시작 순서를 조정합니다. MCP 서버는 ClickHouse가 준비될 때까지 기다리고, LibreChat은 MCP 서버가 준비될 때까지 기다립니다.
  • 공유 환경 파일. .env에는 각 서비스의 자격 증명과 연결 값이 들어 있으며, 서비스들이 서로 통신할 수 있도록 일관되게 설정됩니다. 예를 들어 MCP 서버는 .env의 ClickHouse 자격 증명을 사용해 ClickHouse에 연결합니다. LibreChat에는 LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL이 제공되므로 모든 실행이 기본적으로 Langfuse에 추적됩니다.
ClickHouse는 이 스택에서 두 가지 역할을 합니다. Langfuse의 스토리지 백엔드이면서, 동시에 에이전트가 MCP 서버를 통해 쿼리하는 데이터베이스이기도 합니다.

​
다음 단계

  • 스택의 각 구성 요소가 어떤 역할을 하는지 살펴보십시오: ClickHouse MCP 서버, LibreChat, Langfuse.
  • 스택이 전체적으로 어떻게 구성되는지는 개요에서 확인하십시오.
  • 아무것도 설치하지 않고 공개 데이터셋으로 스택을 사용해 보려면 호스팅 데모인 AgentHouse를 사용하십시오.
마지막 수정일 2026년 6월 29일