00 Configuración

Material del facilitador correspondiente a la lección 00 Configuración del participante.

Tiempos

Unos 25 minutos. Inicia los pasos que pueden ejecutarse en segundo plano (creación del servicio, docker compose up) antes o durante la charla de apertura para que se ejecuten a la vez. Pide a los asistentes que creen las tres cuentas (ClickHouse Cloud, Langfuse y OpenAI) antes del día del taller — cada una tarda entre 5 y 10 minutos — para que este módulo no exceda el tiempo asignado.

En grupos con varias plataformas, reserva otros 10 minutos antes de la sesión para quienes usen Windows y aún no hayan instalado WSL 2 y Docker Desktop. Puede ser necesario reiniciar el equipo después de wsl --install.

Para sesiones presenciales con credenciales proporcionadas por el instructor:

• Entrega a cada participante claves temporales distintas para la organización de ClickHouse Cloud y la API del proyecto de OpenAI. Nunca compartas una sola clave con todo el grupo.
• Envía cada clave por un canal aprobado para compartir secretos, no por chat ni en diapositivas.
• Define un presupuesto y límites de frecuencia para el proyecto de OpenAI y supervisa el uso durante la sesión.
• Revoca ambas claves después del taller. Rota de inmediato cualquier clave que quede expuesta.

Guion de presentación

• Enmarca la sesión: los participantes trasladarán una aplicación existente a ClickHouse Cloud, y el agente se encargará de construirla.
• La CLI solo muestra una vez la contraseña del usuario predeterminado; pide a los participantes que la guarden de inmediato. El cuadro de diálogo Connect del servicio proporciona el nombre de host.
• El módulo 00 ahora crea el servicio en la nube y rellena todas las credenciales, por lo que los pasos que pueden ejecutarse en segundo plano se concentran aquí; el módulo 01 solo crea el esquema en el servicio que ya existe.
• El paso 7 es la única configuración de integración del agente: skills, ClickHouse MCP y ClickStack MCP.
• Pide a los participantes que seleccionen macOS o Windows en el encabezado de la página antes del paso 1. En Windows, PowerShell solo sirve para preparar WSL; todos los comandos del taller se ejecutan en Ubuntu.
• Trata WSL 2 como preparación previa para Windows, no como una instalación durante la sesión. Antes de abrir las puertas, confirma una versión compatible de Windows, permisos de administrador local, virtualización, 16 GB de RAM en el host, 20 GB libres en disco, Ubuntu versión 2 y la integración de Ubuntu con Docker Desktop.

Fallos habituales

• El correo de trabajo ya está asociado a una organización de ClickHouse, por lo que no aparecen los créditos de prueba. Indica que se use un correo personal (se menciona en la preparación previa).
• El agente de programación no puede añadir servidores MCP debido a la política corporativa (lo detecta la prueba rápida de la preparación previa).
• docker compose up falla porque Docker tiene pocos recursos asignados (necesita 6 GB o más).
• El participante con Windows clonó el repositorio en /mnt/c, lo que provoca montajes enlazados lentos o fallos de CRLF. Vuelve a clonarlo en ~/ClickHouse_Demos, dentro de Ubuntu, y configura git config --global core.autocrlf input.
• Docker Desktop está en ejecución, pero Ubuntu no puede acceder a él. Activa el motor de WSL 2 y la integración explícita con Ubuntu y, después, ejecuta wsl --shutdown desde PowerShell.
• El agente de programación abre un checkout independiente en C:\Users mientras los comandos se ejecutan en WSL. Vuelve a abrir la carpeta ~/ClickHouse_Demos de WSL en el agente de escritorio y confirma que su terminal identifica el sistema como Linux mediante uname -s.
• La política corporativa bloquea WSL, la virtualización, Docker Desktop u OAuth. No es posible corregirlo durante el módulo; traslada al participante a un equipo personal o de reserva ya preparado.
• Antes, la primera solicitud después de que un servicio en la nube redujera la escala a cero por inactividad devolvía un error 500; ahora el back-end reintenta la conexión para reactivar el servicio. Por eso, la primera carga del panel puede detenerse unos segundos, pero termina correctamente. No es un fallo que haya que investigar. Confirmado en el ensayo en entorno limpio de julio de 2026.

Pasos de restablecimiento

• Si la prueba de un participante no se puede utilizar, asígnale uno de los servicios de reserva de Cloud.
• Vuelve a ejecutar cp .env.workshop.example .env.workshop y rellena los datos; confirma que no se haya añadido por error ningún .env.workshop al repositorio.
• En Windows, comprueba wsl --status, wsl --version y wsl --list --verbose; Ubuntu debe ser la versión 2. Dentro de Ubuntu, pwd debe empezar por /home/ y docker version debe mostrar Client y Server.
• PENDIENTE: confirmar los comandos de restablecimiento.