00 Configuration

Complément formateur du module participant 00 Configuration.

Durée

Environ 25 minutes. Lancez les étapes qui peuvent s’exécuter en arrière-plan (création du service, docker compose up) avant ou pendant la présentation d’ouverture, afin qu’elles s’exécutent en parallèle. Encouragez les participants à créer les trois comptes (ClickHouse Cloud, Langfuse et OpenAI) avant le jour J — chacun demande entre 5 et 10 minutes — pour que ce module respecte le temps imparti.

Dans les groupes multiplateformes, prévoyez 10 minutes supplémentaires avant la session pour les participants sous Windows qui n’ont pas encore installé WSL 2 et Docker Desktop. Un redémarrage peut être nécessaire après wsl --install.

Pour les sessions en présentiel avec des identifiants fournis par le formateur :

• Remettez à chaque participant des clés temporaires et distinctes pour l’organisation ClickHouse Cloud et l’API du projet OpenAI. Ne partagez jamais une même clé avec toute la salle.
• Transmettez chaque clé par un canal approuvé de partage de secrets, jamais dans le chat ni sur une diapositive.
• Définissez un budget et des limites de débit pour le projet OpenAI, puis surveillez l’utilisation pendant la session.
• Révoquez les deux clés après l’atelier. Renouvelez immédiatement toute clé exposée.

Trame d’animation

• Présentez l’objectif : les participants vont migrer une application existante vers ClickHouse Cloud, et l’agent se chargera de la construction.
• La CLI n’affiche qu’une fois le mot de passe de l’utilisateur par défaut ; demandez aux participants de l’enregistrer immédiatement. La boîte de dialogue Connect du service fournit le nom d’hôte.
• Le module 00 crée désormais le service Cloud et renseigne tous les identifiants : les étapes qui peuvent s’exécuter en arrière-plan sont donc regroupées ici ; le module 01 ne fait que créer le schéma sur le service déjà présent.
• L’étape 7 est la seule configuration d’intégration de l’agent : compétences, ClickHouse MCP et ClickStack MCP.
• Demandez aux participants de choisir macOS ou Windows dans l’en-tête de la page avant l’étape 1. Sous Windows, PowerShell sert uniquement à amorcer WSL ; toutes les commandes de l’atelier s’exécutent dans Ubuntu.
• Considérez WSL 2 comme un prérequis Windows, et non comme une installation à effectuer pendant la session. Avant l’ouverture des portes, vérifiez que la version de Windows est compatible, que l’utilisateur dispose de droits d’administrateur local, que la virtualisation est activée, que l’hôte possède 16 Go de RAM et 20 Go d’espace disque libre, qu’Ubuntu est en version 2 et que son intégration Docker Desktop fonctionne.

Problèmes courants

• L’adresse e-mail professionnelle est déjà rattachée à une organisation ClickHouse : les crédits d’essai n’apparaissent pas. Orientez le participant vers une adresse personnelle (ce point figure dans les prérequis).
• L’agent de programmation ne peut pas ajouter de serveurs MCP en raison de la politique de l’entreprise (ce problème est détecté par le test rapide des prérequis).
• docker compose up échoue parce que Docker manque de ressources (au moins 6 Go sont nécessaires).
• Sous Windows, le participant a cloné le dépôt dans /mnt/c, ce qui ralentit les montages liés ou provoque des erreurs CRLF. Clonez-le de nouveau dans ~/ClickHouse_Demos, au sein d’Ubuntu, et configurez git config --global core.autocrlf input.
• Docker Desktop fonctionne, mais Ubuntu ne peut pas y accéder. Activez le moteur WSL 2 et l’intégration explicite avec Ubuntu, puis exécutez wsl --shutdown depuis PowerShell.
• L’agent de programmation ouvre un checkout distinct dans C:\Users alors que les commandes s’exécutent dans WSL. Rouvrez le dossier WSL ~/ClickHouse_Demos dans l’agent de bureau et vérifiez que son terminal indique Linux avec uname -s.
• La politique de l’entreprise bloque WSL, la virtualisation, Docker Desktop ou OAuth. Ce problème ne peut pas être résolu pendant le module ; installez le participant sur un ordinateur personnel ou de prêt déjà préparé.
• Auparavant, la première requête après la mise à l’échelle zéro d’un service Cloud inactif renvoyait une erreur 500 ; le back-end réessaie désormais la connexion afin de réveiller le service. Le premier chargement du tableau de bord peut donc marquer une pause de quelques secondes, mais il aboutit. Ce n’est pas une panne à diagnostiquer. Comportement confirmé lors de la répétition en environnement vierge de juillet 2026.

Procédures de réinitialisation

• Orientez un participant bloqué vers le pool de services Cloud de prêt si son essai est inutilisable.
• Exécutez de nouveau cp .env.workshop.example .env.workshop et renseignez les valeurs ; vérifiez qu’aucun .env.workshop n’a été ajouté au dépôt par erreur.
• Sous Windows, vérifiez wsl --status, wsl --version et wsl --list --verbose ; Ubuntu doit être en version 2. Dans Ubuntu, pwd doit commencer par /home/ et docker version doit afficher Client et Server.
• À FAIRE : confirmer les commandes de réinitialisation.