00 Configuração

Material do facilitador correspondente à lição 00 Configuração do participante.

Cronograma

Cerca de 25 minutos. Inicie as etapas que podem rodar em segundo plano (criação do serviço, docker compose up) antes ou durante a apresentação de abertura, para que elas sejam executadas em paralelo. Oriente os participantes a criar as três contas (ClickHouse Cloud, Langfuse e OpenAI) antes do dia do evento — cada uma leva de 5 a 10 minutos — para que este módulo permaneça dentro do tempo previsto.

Para turmas com diferentes plataformas, reserve mais 10 minutos antes da sessão para os participantes no Windows que ainda não instalaram o WSL 2 e o Docker Desktop. Talvez seja necessário reiniciar o computador após wsl --install.

Para sessões presenciais com credenciais fornecidas pelo instrutor:

• Forneça a cada participante chaves temporárias e distintas para a organização do ClickHouse Cloud e a API do projeto OpenAI. Nunca compartilhe a mesma chave com toda a turma.
• Entregue cada chave por um canal aprovado de compartilhamento de segredos, não pelo chat nem em slides.
• Defina um orçamento e limites de taxa para o projeto OpenAI e monitore o uso durante a sessão.
• Revogue ambas as chaves após o workshop. Substitua imediatamente qualquer chave que seja exposta.

Roteiro de apresentação

• Contextualize a sessão: os participantes migrarão um aplicativo existente para o ClickHouse Cloud, e o agente fará o trabalho de construção.
• A CLI exibe a senha do usuário padrão uma única vez; peça aos participantes que a salvem imediatamente. A caixa de diálogo Connect do serviço fornece o nome do host.
• O módulo 00 agora cria o serviço na nuvem e preenche todas as credenciais, concentrando aqui as etapas que podem rodar em segundo plano; o módulo 01 apenas cria o esquema no serviço que já existe.
• A etapa 7 é a única configuração de integração do agente: skills, ClickHouse MCP e ClickStack MCP.
• Peça aos participantes que escolham macOS ou Windows no cabeçalho da página antes da etapa 1. No Windows, o PowerShell serve apenas para inicializar o WSL; todos os comandos do workshop são executados no Ubuntu.
• Trate o WSL 2 como preparação prévia no Windows, não como uma instalação durante a sessão. Antes da abertura das portas, confirme que a versão do Windows é compatível, que há direitos de administrador local, virtualização, 16 GB de RAM no host, 20 GB livres em disco, Ubuntu versão 2 e integração do Ubuntu com o Docker Desktop.

Falhas comuns

• O e-mail corporativo já está associado a uma organização do ClickHouse, por isso os créditos de avaliação não aparecem. Oriente o participante a usar um e-mail pessoal (isso é mencionado na preparação prévia).
• O agente de programação não consegue adicionar servidores MCP devido à política corporativa (identificado pelo teste rápido da preparação prévia).
• docker compose up falha porque os recursos alocados ao Docker são insuficientes (são necessários pelo menos 6 GB).
• O participante no Windows clonou o repositório em /mnt/c, o que deixa as montagens vinculadas lentas ou causa falhas de CRLF. Clone novamente em ~/ClickHouse_Demos, dentro do Ubuntu, e defina git config --global core.autocrlf input.
• O Docker Desktop está em execução, mas o Ubuntu não consegue acessá-lo. Ative o mecanismo do WSL 2 e a integração explícita com o Ubuntu e, em seguida, execute wsl --shutdown no PowerShell.
• O agente de programação abre um checkout separado em C:\Users, enquanto os comandos são executados no WSL. Reabra a pasta ~/ClickHouse_Demos do WSL no agente para desktop e confirme que o terminal identifica o sistema como Linux ao executar uname -s.
• A política corporativa bloqueia WSL, virtualização, Docker Desktop ou OAuth. Não é possível corrigir isso durante o módulo; transfira o participante para um computador pessoal ou de reserva já preparado.
• Antes, a primeira solicitação depois que um serviço na nuvem entrava em escala zero por inatividade retornava o erro 500; agora, o back-end repete a conexão para reativar o serviço. Portanto, o primeiro carregamento do painel pode pausar por alguns segundos, mas será concluído. Não trate isso como falha. Comportamento confirmado no ensaio em ambiente limpo de julho de 2026.

Etapas de redefinição

• Se o período de avaliação de um participante estiver inutilizável, direcione-o a um dos serviços de reserva do Cloud.
• Execute novamente cp .env.workshop.example .env.workshop e preencha os dados outra vez; confirme que não há nenhum .env.workshop adicionado indevidamente ao repositório.
• No Windows, verifique wsl --status, wsl --version e wsl --list --verbose; o Ubuntu deve ser a versão 2. Dentro do Ubuntu, pwd deve começar com /home/, e docker version deve mostrar Client e Server.
• PENDENTE: confirmar os comandos de redefinição.