00 Configuration

Créez les services cloud, installez les clients locaux, connectez votre agent une seule fois et démarrez l’application locale.

Les commandes de cette page utilisent les valeurs enregistrées dans .env.workshop.

Choisissez macOS ou Windows dans l’en-tête de la page avant de commencer. Votre choix reste actif pendant tout l’atelier. Sous Windows, vous utilisez Ubuntu sur WSL 2 : les mêmes commandes Bash, Docker, ClickHouse et d’agent fonctionnent donc dans chaque module.

Résultat attendu

En environ 25 minutes, vous disposerez des éléments suivants :

un service ClickHouse Cloud et une clé API d’organisation ;
clickhousectl et le client de base de données clickhouse ;
les compétences ClickHouse, ainsi que les connexions MCP ClickHouse et ClickStack dans votre agent de programmation ;
des clés Langfuse et OpenAI ;
l’application opérationnelle sur localhost:8080.

ClickHouse, Postgres, ClickPipes, ClickStack/HyperDX, Langfuse et les points de terminaison MCP sont hébergés dans le cloud. Seuls l’application de l’atelier, les outils CLI et clients, l’agent de programmation, le générateur de charge et le collecteur de télémétrie sans état s’exécutent sur votre machine.

Après l’étape 2, exécutez toutes les commandes depuis le répertoire de l’application, sauf indication contraire.

Étape 1 — Vérifier les prérequis

Il vous faut Docker avec au moins 6 Go de mémoire, Git, Node.js 22 ou version ultérieure, Python 3 et un agent de programmation compatible MCP : Claude Code, Cursor, Codex CLI ou Windsurf.

Configuration sous macOS

Installez Docker Desktop pour Mac et allouez-lui au moins 6 Go dans Settings -> Resources. Ouvrez Terminal et exécutez :

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

Ne poursuivez que lorsque chaque commande affiche une version et que docker version présente à la fois une section Client et une section Server.

Ordinateur géré par votre organisation ?

La politique de l’entreprise peut bloquer l’installation MCP ou OAuth dans le navigateur. Utilisez une machine personnelle ou contactez votre administrateur si l’étape OAuth de l’étape 7 ne peut pas s’ouvrir.

Étape 2 — Cloner le dépôt et activer la branche de l’atelier

Exécutez ceci dans Terminal sous 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

Laissez ce terminal ouvert dans ClickHouse_Demos/workshops/build_workshop/app. Sous Windows, il s’agit du terminal Ubuntu. Le script de vérification préalable est ./preflight.sh dans ce répertoire. Restez sur build-workshop-v1, sauf pendant les tests de panne du module 07. Confirmez maintenant la branche :

git branch --show-current

Résultat attendu : build-workshop-v1.

Étape 3 — Créer un compte ClickHouse Cloud et une clé API

Avant le jour de l’atelier : créez les trois comptes

Si vous participez à un atelier planifié, créez à l’avance vos comptes ClickHouse Cloud, Langfuse et OpenAI. Chaque inscription peut nécessiter 5 à 10 minutes d’attente pour une vérification par e-mail ou téléphone. Revenez ici pendant la configuration pour créer les clés et les ressources utilisées dans les exercices.

Formation en présentiel : utilisez la clé API d’organisation ClickHouse Cloud propre au participant, remise de manière sécurisée par votre formateur, puis ignorez cette étape.

Connectez-vous ou commencez un essai sur console.clickhouse.cloud.
Ouvrez API Keys, créez une clé d’organisation Admin, puis enregistrez son identifiant et son secret.

Le secret n’est affiché qu’une seule fois. Conservez-le hors du dépôt ; ne l’inscrivez pas dans .env.workshop.

Étape 4 — Installer `clickhousectl`

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

Ajoutez ~/.local/bin à votre profil d’interpréteur si un nouveau terminal ne trouve pas clickhousectl. Sous Windows, installez-le et exécutez-le dans Ubuntu ; n’utilisez pas d’exécutable Windows dans PowerShell.

Étape 5 — Authentifier `clickhousectl`

Utilisez la clé API de l’étape 3. Le formulaire interactif évite de conserver le secret dans l’historique de l’interpréteur :

clickhousectl cloud auth login --interactive

Une automatisation de confiance peut utiliser la forme explicite attendue par la CLI :

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

Vérifiez à la fois les identifiants enregistrés et l’accès au Cloud :

clickhousectl cloud auth status
clickhousectl cloud org list

clickhousectl stocke les identifiants du projet sous .clickhouse/ dans le répertoire courant. Continuez d’exécuter les commandes Cloud depuis le répertoire de l’application et ne versionnez ni ne partagez jamais ce dossier.

Étape 6 — Créer le service ClickHouse

Choisissez la région que vous utiliserez aussi pour Postgres au module 03. Remplacez si nécessaire la région de l’exemple :

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

Enregistrez l’identifiant du service et le mot de passe à usage unique de l’utilisateur default renvoyés. Vérifiez que le service est prêt :

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

Installez un client de la même version majeure et mineure que le service Cloud. Vous éviterez ainsi les avertissements de paramètre inconnu qu’un client stable plus récent peut produire face à un serveur Cloud légèrement plus ancien :

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 installe uniquement le binaire client ; il ne démarre aucun serveur ClickHouse. Toutes les requêtes de l’atelier ciblent ClickHouse Cloud. Depuis la boîte de dialogue Connect du service, copiez le nom d’hôte et vérifiez le client. L’option --password demande le mot de passe sans l’afficher :

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

Résultat attendu : une ligne contenant la version de ClickHouse et default.

Étape 7 — Configurer une seule fois les compétences de l’agent et les deux serveurs MCP

Ces intégrations ont des rôles distincts :

Intégration	Rôle	Utilisée dans
Compétences ClickHouse	Examiner le schéma et le SQL selon les pratiques ClickHouse	Modules 01 et 03
MCP ClickHouse (`/mcp`)	Lire votre service au moyen de requêtes `SELECT`	Modules 01 et 04
MCP ClickStack (`/clickstack`)	Rechercher dans la télémétrie et enregistrer des artefacts SRE	Modules 06 et 07

Commencez par installer les compétences pour votre agent :

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

Dans ClickHouse Cloud, ouvrez la boîte de dialogue Connect de votre service et activez Connect with MCP. Ajoutez ensuite les deux points de terminaison et terminez OAuth dans le navigateur :

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

Ajoutez ceci une seule fois à .cursor/mcp.json, puis autorisez les deux serveurs dans les paramètres de Cursor :

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

Ajoutez ceci une seule fois à ~/.codeium/windsurf/mcp_config.json, puis autorisez les deux serveurs :

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

Vérifiez maintenant la connexion ClickHouse :

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

Il est normal que ClickStack renvoie un résultat vide tant que le module 05 n’a pas envoyé de télémétrie. Ne répétez pas la configuration MCP plus tard ; les modules 06 et 07 utilisent la connexion clickstack configurée ici.

Étape 8 — Créer les clés Langfuse et OpenAI

Langfuse enregistre les traces du chat IA utilisées au module 08.

Formation en présentiel : utilisez la clé API du projet OpenAI propre au participant, remise de manière sécurisée par votre formateur, et ignorez le point 3. Vous avez tout de même besoin des clés Langfuse des points 1 et 2.

Créez un projet dans Langfuse Cloud aux États-Unis ou Langfuse Cloud en Europe.
Créez une paire de clés API de projet et enregistrez les clés publique et secrète.
Créez une clé API limitée au projet sur platform.openai.com/api-keys, puis activez la facturation.

Utilisez l’URL Langfuse correspondant à la région dans laquelle vous avez créé le projet :

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

OPENAI_API_KEY=sk-...

Conservez les valeurs par défaut du modèle et de la base de l’API déjà présentes dans .env.workshop.

Étape 9 — Renseigner `.env.workshop`

Copiez les valeurs du service obtenues à l’étape 6 et les clés de l’étape 8 dans les champs existants :

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’exportez pas ces noms dans l’interpréteur : les valeurs exportées remplacent celles du fichier d’environnement.

Étape 10 — Exécuter la vérification préalable et démarrer l’application

Les commandes ci-dessous accèdent au bon répertoire depuis n’importe quel emplacement du dépôt cloné :

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

Ne poursuivez que lorsque la dernière ligne indique Overall: READY. Appliquez toute correction affichée, puis réexécutez le script. Démarrez ensuite la pile :

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

Au bout d’environ deux minutes, les conteneurs locaux backend et frontend de l’application doivent afficher l’état healthy, et l’application doit se charger sur localhost:8080. Aucun serveur de base de données ne démarre en local. Des tableaux de bord vides sont normaux jusqu’au module 01.

Vérification finale

clickhousectl cloud service get <service-id> indique que le service est prêt.
clickhouse client ... --query "SELECT version()" réussit.
Votre agent répertorie les bases de données par l’intermédiaire du MCP ClickHouse.
./preflight.sh se termine par Overall: READY depuis le répertoire de l’application.
Les services Docker sont opérationnels et l’application locale se charge.

Passez à 01 ClickHouse Cloud.