00 Configuração

Crie os serviços na nuvem, instale os clientes locais, conecte seu agente uma única vez e inicie o aplicativo local.

Os comandos desta página usam os valores salvos em .env.workshop.

Escolha macOS ou Windows no cabeçalho da página antes de começar. Sua escolha permanecerá ativa durante todo o workshop. No Windows, usa-se o Ubuntu com WSL 2, para que os mesmos comandos de Bash, Docker, ClickHouse e agente funcionem em todos os módulos.

Resultado

Em cerca de 25 minutos, você terá:

um serviço ClickHouse Cloud e uma chave de API da organização;
clickhousectl e o cliente de banco de dados clickhouse;
skills do ClickHouse e conexões MCP do ClickHouse e do ClickStack no seu agente de programação;
chaves do Langfuse e da OpenAI;
o aplicativo íntegro em localhost:8080.

Os endpoints do ClickHouse, Postgres, ClickPipes, ClickStack/HyperDX, Langfuse e MCP ficam hospedados na nuvem. Somente o aplicativo do workshop, as ferramentas de CLI/cliente, o agente de programação, o gerador de carga e o coletor de telemetria sem estado são executados no seu computador.

Depois da etapa 2, execute todos os comandos a partir do diretório do aplicativo, a menos que uma etapa diga o contrário.

Etapa 1 — Confira os pré-requisitos

Você precisa do Docker com pelo menos 6 GB de memória, Git, Node.js 22+, Python 3 e um agente de programação compatível com MCP: Claude Code, Cursor, Codex CLI ou Windsurf.

Configuração no macOS

Instale o Docker Desktop para Mac e aloque pelo menos 6 GB em Settings -> Resources. Abra o Terminal e execute:

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

Prossiga somente quando todos os comandos exibirem uma versão e docker version mostrar as seções Client e Server.

Laptop gerenciado?

A política corporativa pode bloquear a instalação do MCP ou o OAuth no navegador. Use um computador pessoal ou consulte seu administrador se não for possível abrir a etapa de OAuth na etapa 7.

Etapa 2 — Clone o repositório e mude para o branch do workshop

Execute no Terminal do 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

Mantenha este terminal em ClickHouse_Demos/workshops/build_workshop/app. No Windows, isso significa usar o terminal do Ubuntu. O script de verificação prévia é ./preflight.sh dentro deste diretório. Permaneça em build-workshop-v1, exceto durante os testes de falha do módulo 07. Confirme o branch agora:

git branch --show-current

Resultado esperado: build-workshop-v1.

Etapa 3 — Crie uma conta e uma chave de API no ClickHouse Cloud

Antes do dia do workshop: crie as três contas

Se você participar de um workshop agendado, crie antecipadamente suas contas do ClickHouse Cloud, Langfuse e OpenAI. Cada cadastro pode levar de 5 a 10 minutos, devido à espera pela verificação por e-mail ou telefone. Volte aqui durante a configuração para criar as chaves e os recursos usados nos exercícios.

Treinamento presencial: use a chave de API da organização do ClickHouse Cloud exclusiva para o participante, fornecida com segurança pelo instrutor, e pule esta etapa.

Entre ou inicie um período de avaliação em console.clickhouse.cloud.
Abra API Keys, crie uma chave de organização Admin e salve o Key ID e o segredo.

O segredo é exibido uma única vez. Armazene-o fora do repositório; não o coloque em .env.workshop.

Etapa 4 — Instale o `clickhousectl`

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

Adicione ~/.local/bin ao perfil do shell caso um novo terminal não encontre clickhousectl. No Windows, instale-o e execute-o dentro do Ubuntu; não use um executável do Windows no PowerShell.

Etapa 5 — Autentique o `clickhousectl`

Use a chave de API da etapa 3. O modo interativo mantém o segredo fora do histórico do shell:

clickhousectl cloud auth login --interactive

Uma automação confiável pode usar o formato explícito esperado pela CLI:

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

Verifique as credenciais salvas e o acesso ao Cloud:

clickhousectl cloud auth status
clickhousectl cloud org list

O clickhousectl armazena as credenciais do projeto em .clickhouse/, no diretório atual. Continue executando os comandos do Cloud a partir do diretório do aplicativo e nunca adicione nem compartilhe essa pasta.

Etapa 6 — Crie o serviço ClickHouse

Escolha a região que você também usará para o Postgres no módulo 03. Substitua a região de exemplo se necessário:

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

Salve o service ID e a default-user password de uso único retornados. Verifique a prontidão:

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

Instale um cliente da mesma versão principal/secundária do serviço na nuvem. Assim, você evita os avisos de configuração desconhecida que um cliente stable mais recente pode emitir ao se conectar a um servidor na nuvem ligeiramente mais antigo:

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 instala somente o binário do cliente; ele não inicia um servidor ClickHouse. Todas as consultas do workshop são direcionadas ao ClickHouse Cloud. Na caixa de diálogo Connect do serviço, copie o nome do host e verifique o cliente. A opção --password solicita a senha sem exibi-la:

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()"

Resultado esperado: uma linha contendo a versão do ClickHouse e default.

Etapa 7 — Configure uma única vez as skills do agente e os dois servidores MCP

Essas integrações têm funções distintas:

Integração	Finalidade	Uso
Skills do ClickHouse	Revisar o esquema e o SQL de acordo com as práticas do ClickHouse	Módulos 01 e 03
ClickHouse MCP (`/mcp`)	Ler seu serviço com consultas `SELECT`	Módulos 01 e 04
ClickStack MCP (`/clickstack`)	Pesquisar a telemetria e salvar artefatos de SRE	Módulos 06 e 07

Primeiro, instale as skills para seu agente:

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

No ClickHouse Cloud, abra a caixa de diálogo Connect do serviço e ative Connect with MCP. Depois, adicione ambos os endpoints e conclua o OAuth no navegador:

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

Adicione isto uma única vez a .cursor/mcp.json e, depois, autorize os dois servidores nas configurações do Cursor:

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

Adicione isto uma única vez a ~/.codeium/windsurf/mcp_config.json e, depois, autorize os dois servidores:

{
  "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"]
    }
  }
}

Verifique agora a conexão com o ClickHouse:

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

Um resultado vazio no ClickStack é esperado até o módulo 05 enviar telemetria. Não repita a configuração do MCP mais adiante; os módulos 06 e 07 usam a conexão clickstack configurada aqui.

Etapa 8 — Crie chaves do Langfuse e da OpenAI

O Langfuse registra os traces do chat com IA usados no módulo 08.

Treinamento presencial: use a chave de API do projeto OpenAI exclusiva para o participante, fornecida com segurança pelo instrutor, e pule o item 3. Você ainda precisa das chaves do Langfuse dos itens 1 e 2.

Crie um projeto no Langfuse Cloud dos EUA ou no Langfuse Cloud da UE.
Crie um par de chaves de API do projeto e salve as chaves pública e secreta.
Crie uma chave de API limitada ao projeto em platform.openai.com/api-keys e ative o faturamento.

Use a URL do Langfuse correspondente à região em que você criou o projeto:

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

OPENAI_API_KEY=sk-...

Mantenha os valores padrão do modelo e da base da API que já estão em .env.workshop.

Etapa 9 — Preencha `.env.workshop`

Copie os valores do serviço da etapa 6 e as chaves da etapa 8 para os campos existentes:

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

Não exporte esses nomes no shell: os valores exportados substituem os do arquivo de ambiente.

Etapa 10 — Execute a verificação prévia e inicie o aplicativo

Os comandos abaixo entram no diretório correto a partir de qualquer local dentro do repositório clonado:

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

Prossiga somente quando a última linha for Overall: READY. Aplique qualquer correção exibida e execute o script novamente. Depois, inicie a pilha:

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

Em cerca de dois minutos, os contêineres locais backend e frontend do aplicativo devem informar healthy, e o aplicativo deve abrir em localhost:8080. Nenhum servidor de banco de dados é iniciado localmente. Os painéis vazios estão corretos até o módulo 01.

Verificação de conclusão

clickhousectl cloud service get <service-id> informa que o serviço está pronto.
clickhouse client ... --query "SELECT version()" é executado com sucesso.
Seu agente lista os bancos de dados por meio do ClickHouse MCP.
./preflight.sh termina com Overall: READY no diretório do aplicativo.
Os serviços do Docker estão íntegros, e o aplicativo local abre.

Continue em 01 ClickHouse Cloud.