Configure o Agentic Data Stack com Docker Compose

Execute todo o Agentic Data Stack (ClickHouse, LibreChat, o servidor MCP e Langfuse) com Docker Compose

Execute o Agentic Data Stack completo localmente com Docker Compose e faça perguntas aos seus dados desde o primeiro acesso. Um único comando docker compose up inicializa o LibreChat, o ClickHouse MCP server, o ClickHouse e o Langfuse para observabilidade.

​

Pré-requisitos

• Docker com o plugin Compose (Compose v2 ou posterior).
• Git, para clonar o repositório.
• Uma chave de API de um provedor de modelos (como OpenAI, Anthropic ou Google). O agente precisa de um modelo para responder a perguntas, então forneça uma chave durante a configuração ou adicione uma na UI do LibreChat antes do seu primeiro chat.

​

Coloque a stack em funcionamento

1. Clone o repositório

   git clone https://github.com/ClickHouse/agentic-data-stack
   cd agentic-data-stack
   

   O repositório inclui um docker-compose.yml na raiz, então toda a stack pode ser iniciada com um único comando. Veja Architecture para a lista completa de serviços.

2. Execute o script de Setup da demo

   ./scripts/prepare-demo.sh
   

   Isso gera um arquivo .env com credenciais para cada serviço e, em seguida, exibe um menu interativo para configurar chaves de API para o provedor escolhido. Você também pode definir essas chaves diretamente no arquivo .env. Qualquer provedor que você pular continuará definido como user_provided, para que você possa adicionar sua própria chave na UI do LibreChat.

   Na primeira inicialização, a stack cria um usuário Admin a partir do .env. O login padrão é [e-mail] / password.

   Defina suas próprias credenciais de login

   Execute generate-env.sh com estas variáveis antes de prepare-demo.sh:

   USER_EMAIL="[e-mail]" USER_PASSWORD="supersecret" USER_NAME="YourName" ./scripts/generate-env.sh
   

   O prepare-demo.sh detectará o .env existente e irá direto para a configuração das chaves de API.

3. Inicie os serviços em segundo plano

   docker compose up -d
   

   A inicialização é ordenada automaticamente. O LibreChat só inicia depois que o servidor MCP estiver íntegro, então a conexão com o ClickHouse já estará pronta no primeiro carregamento.

4. Abra o LibreChat e faça login

   Quando a stack estiver em execução, os serviços estarão disponíveis no navegador:

   • LibreChat (UI de chat) — http://localhost:3080
   • Langfuse (observabilidade) — http://localhost:3000
   • Painel de Admin (configuração do LibreChat no navegador) — http://localhost:3081
   • Console do MinIO (armazenamento de objetos; credenciais em .env) — http://localhost:9091

   Faça login no LibreChat com as credenciais de Admin do seu arquivo .env.

5. Selecione um modelo

   Um modelo já vem selecionado por padrão. Se quiser alterá-lo, abra o seletor de modelos e escolha o que deseja usar.

   Se você não definiu uma chave do provedor durante o Setup, adicione uma na UI.

   Defina uma chave do provedor na UI

   Abra o seletor de modelos e clique em Set API Key ao lado do provedor.

   Cole sua chave na caixa de diálogo e clique em Submit. Você pode definir uma expiração ou manter a chave sem expiração.

6. Selecione o servidor MCP

   A stack pré-configura seus servidores MCP no librechat.yaml do LibreChat. Na área de composição da mensagem, clique em MCP Servers e selecione ClickHouse-Local.

   Selecione ClickHouse-Cloud para usar um serviço ClickHouse Cloud.

7. Faça sua primeira pergunta

   Por exemplo:

   Quais bancos de dados e tabelas estão disponíveis, e quantas linhas há na maior tabela?

   O agente usa as ferramentas do servidor MCP para listar bancos de dados e tabelas, executar consultas em modo somente leitura no ClickHouse e montar uma resposta com base nos resultados. Você não precisa escrever SQL.

​

Pare ou redefina a stack

Pare os serviços sem excluir nada:

docker compose down

Para encerrar todos os contêineres e apagar todos os volumes para começar do zero, use o script de redefinição da stack:

./scripts/reset-all.sh

​

Arquitetura

docker-compose.yml é um ponto de entrada simples que inclui quatro arquivos Compose:

Arquivo Compose	Define
langfuse-compose.yml	Langfuse e seus serviços subjacentes (ClickHouse, PostgreSQL, Redis, MinIO)
clickhouse-mcp-compose.yml	O servidor MCP do ClickHouse
librechat-compose.yml	LibreChat e seus serviços subjacentes (MongoDB, Meilisearch, pgvector, RAG API)
admin-panel-compose.yml	O painel Admin do LibreChat

Dois detalhes fazem a inicialização com um único comando funcionar:

• Health checks e ordem de inicialização. O Compose usa health checks para sequenciar a inicialização. O servidor MCP espera o ClickHouse ficar disponível, e o LibreChat espera pelo servidor MCP.
• Arquivo de ambiente compartilhado. O .env armazena as credenciais e os valores de conexão de cada serviço, definidos de forma consistente para que os serviços consigam se comunicar entre si. Por exemplo, o servidor MCP se conecta ao ClickHouse usando as credenciais do ClickHouse definidas no .env. O LibreChat recebe LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY e LANGFUSE_BASE_URL, para que cada execução seja rastreada no Langfuse desde o início.

O ClickHouse desempenha dois papéis na stack: ele é tanto o backend de armazenamento do Langfuse quanto o banco de dados que seu agente consulta por meio do servidor MCP.

​

Próximas etapas

• Entenda o papel de cada componente da stack: ClickHouse MCP server, LibreChat e Langfuse.
• Consulte a visão geral para entender como a stack se integra.
• Para experimentar a stack com conjuntos de dados públicos sem instalar nada, use o AgentHouse, a demo hospedada.