Vous avez cloné un repository et vous y trouvez un script Bash exécuté par le pipeline CI. Trois cents lignes, aucun commentaire. Vous devez comprendre ce qu'il fait avant de le modifier. Vous pouvez le lire attentivement, chercher la signification des flags, suivre la logique. Ou vous pouvez l'envoyer à ai-explain.

Même histoire pour les stack traces. Une erreur React en production avec six frames de sortie minifiée. Un Fatal error PHP à la ligne 847 d'un fichier que vous n'avez jamais ouvert. Un build Docker qui échoue sur une étape RUN que vous n'avez pas écrite.

ai-explain est la version terminal du composant de tooltip ELI5 de ce blog — la même idée « explique-moi comme si j'avais cinq ans », mais dans votre shell plutôt que dans le navigateur.

Expliquer un script que vous n'avez pas écrit

$ ai-explain deploy.sh

This script automates deploying an application using Docker and Docker Compose. It first checks that `docker`, `git`, and `curl` are installed, exiting if any are missing. It pulls the latest code from the `main` branch and builds a new Docker image tagged with the current git commit hash. Then it starts the app service in detached mode without restarting dependent services. After starting the service, it waits up to 60 seconds (12 attempts of 5 seconds each) checking if the app responds with HTTP 200 at `/health`. If successful, it prints a success message and exits. If the health check fails after all attempts, it reports the failure and exits with error code 1. The script modifies the local Docker environment by building a new image and starting containers, but doesn't change any files on disk except through Git operations. Risks include failing to start the app or timing out if the service takes longer than 60 seconds to become healthy. To fix potential issues, ensure all prerequisites are installed and the app's health endpoint is correctly configured.
▋

Voilà toute l'interaction : un chemin de fichier en entrée, une explication en langage clair en sortie — les prérequis, le tag d'image basé sur le hash du commit, le redémarrage avec --no-deps, le health check de 60 secondes et ce qui se passe en cas de timeout.

Pourquoi ça fonctionne

ai-explain gère trois modes d'entrée, vérifiés dans cet ordre : l'entrée via pipe (donc cat file | ai-explain l'emporte toujours, même si un nom de fichier est aussi passé), un fichier existant, ou du texte inline pour une question rapide — une seule fonction couvre « explique-moi ce fichier » et « explique-moi cette erreur » sans commandes séparées à retenir. Le prompt demande quinze lignes de texte maximum, jamais une copie de l'entrée, et transmet uname -s pour que les commandes suggérées correspondent à la plateforme sur laquelle vous êtes réellement.

Installation

Tout tourne sur votre machine : zsh, curl et jq (qui construit la requête envoyée à Ollama), et un serveur Ollama accessible — voir installer Ollama si vous n'en avez pas encore.

1. Créez les fichiers. Chaque fonction de cette série vit dans son propre fichier dans ~/.zsh/fns/. La commande ci-dessous crée ce dossier et les deux fichiers d'un coup — ou téléchargez le ZIP, ou créez chaque fichier à la main et collez-y son contenu. _ollama.zsh est la fondation partagée par toute la série, présentée dans ai-test : si un article précédent vous l'a déjà donné, la copie ici est le même fichier.

2. Chargez le dossier depuis ~/.zshrc. Déjà fait si vous avez suivi un article précédent de cette série. Sinon, ajoutez ces lignes à la fin de ~/.zshrc — elles sourcent chaque fichier .zsh du dossier, donc la prochaine fonction que vous ajouterez ne demandera aucune modification ici :

for fn_file in ~/.zsh/fns/*.zsh; do
  source "$fn_file"
done

3. Ouvrez un nouveau terminal (ou lancez exec zsh dans celui en cours), et vérifiez que le shell connaît la nouvelle fonction :

type ai-explain

ai-explain is a shell function from …/ai-explain.zsh signifie que vous êtes prêt. ai-explain not found signifie qu'il manque l'étape 2.

Autres démos

Expliquer une stack trace

$ ai-explain example-error.txt

The error happens because the code tries to call `.map()` on a variable that is `undefined` in the ProductList component. This occurs at line 42 of ProductList.jsx where it expects an array but gets nothing.

To fix this, add a check to ensure the data exists before mapping:
```jsx
{products && products.map(product => (
  <div key={product.id}>{product.name}</div>
))}
```

If `products` is undefined, the component won't crash and will render nothing instead of throwing an error.
▋

Envoyer la sortie de n'importe quelle commande

Le pattern le plus utile : lancez une commande qui échoue et envoyez sa sortie directement :

docker build . 2>&1 | ai-explain

npm install 2>&1 | ai-explain

./run-tests.sh 2>&1 | tail -50 | ai-explain

Le 2>&1 redirige stderr vers stdout pour que les deux streams arrivent dans le pipe. Sans lui, les messages d'erreur de la plupart des outils CLI n'atteignent jamais ai-explain.

Pour les commandes qui produisent beaucoup de sortie, passez d'abord par tail pour ne garder que la fin pertinente (là où les erreurs atterrissent généralement).

Utilisation depuis le dispatcher ai

Comme toutes les fonctions de cette série, ai-explain s'enregistre dans le registre AI_COMMANDS. Le dispatcher ai (issu de _ollama.zsh) liste chaque fonction enregistrée — ici avec les fonctions publiées de cette série installées :

$ ai

ai >
  ai-blog-search — ask your blog a question (RAG over every published article)
  ai-commit  — draft a Conventional Commits message from staged changes
  ai-data <file.json|file.csv>  — suggest jq/awk commands tailored to this file
  ai-diagram <description>|<file>  — turn a description or a config file into a Mermaid diagram
  ai-explain [file|text]  — explain a script, an error or piped output in plain English
  ai-review  — code review of staged changes (SOLID, magic constants, naming)
  ai-secrets  — scan staged changes for hardcoded credentials
  ai-summarize <file> [points]  — summarize a document locally (default: 5 points)
  ai-test <file.sh|.php|.py>  — generate or complete a unit test suite
  ai-translate <file> [language]  — translate a document locally (default: French)

Sélectionnez ai-explain et le dispatcher ouvre d'abord son sélecteur de fichiers fzf : AI_PARAMS[explain]="file" lui indique de demander un fichier plutôt qu'une ligne de texte.

Sous le capot (passez votre chemin si vous voulez juste l'utiliser)

Quand ai-explain est le plus utile

• Scripts hérités : comprendre ce que fait un script CI/CD avant de le modifier
• Erreurs inconnues : une stack trace d'un langage ou d'un framework que vous maîtrisez mal
• Sorties de log cryptiques : avertissements du daemon Docker, entrées du journal systemd, messages du kernel
• Archéologie de one-liners : cette commande awk '{ split($0,a,":"); ... }' trouvée dans un Makefile
• Vérification rapide : est-ce que ce script fait bien ce que son nom suggère ?

C'est aussi utile comme outil d'apprentissage : envoyez-lui un script que vous avez écrit vous-même et voyez si l'explication correspond à votre intention. Si ce n'est pas le cas, soit l'explication est fausse (ça arrive), soit le script contient un bug subtil.

Conclusion

ai-explain rejoint la série « Ollama daily use ».

La série a commencé avec ai-test (la fondation : _ollama.zsh, le dispatcher, le registre AI_COMMANDS) et s'est enrichie de fonctions une par une — chacune résolvant un problème précis de workflow dans le terminal avec un LLM local :

• Workflow du développeur : ai-review, ai-secrets, ai-commit, ai-standup
• Opérations : ai-ci, ai-fix
• Assistance shell : ai-ask, ai-data, ai-diagram
• Travail documentaire : ai-translate, ai-summarize, ai-diff
• Votre propre documentation : ai-blog-search
• Explication : ai-explain

Toutes partagent la même fondation _ollama_query. Ensemble, elles couvrent les moments d'une journée de développement où vous iriez normalement chercher dans un navigateur ou une IA dans le cloud — mais où un modèle local est plus rapide d'accès et garde tout sur votre machine.

Les fonctions sans lien sont encore à venir. Lancez ai pour voir ce que votre terminal sait déjà faire.

J'ai écrit Pandas — merge two or more files il y a quelque temps pour exactement ce genre de travail, et ça marche, mais cela implique d'écrire un script : importer pandas, lire les fichiers, fusionner, peut-être réexporter. La plupart du temps, ce que je veux vraiment, c'est une requête, lancée une fois, qui répond une fois. awk gère la version simple de tout ça — grouper et compter, filtrer — mais dès que j'ai besoin d'un vrai JOIN ou d'une fonction de fenêtrage, me revoilà à écrire du Python pour une question qui tient littéralement en une ligne de SQL.

Démo

order_id,region,amount
1001,EMEA,120.50
1002,APAC,89.00
1003,EMEA,45.20
1004,AMER,300.00
1005,APAC,60.75

[
  { "region": "EMEA", "manager": "Alice Martin" },
  { "region": "APAC", "manager": "Chloé Bernard" },
  { "region": "AMER", "manager": "Bruno Dupont" }
]

$ duckdb -c "SELECT region, COUNT(*) AS orders, SUM(amount) AS total FROM 'orders.csv' GROUP BY region ORDER BY total DESC"

┌─────────┬────────┬────────┐
│ region  │ orders │ total  │
│ varchar │ int64  │ double │
├─────────┼────────┼────────┤
│ AMER    │      1 │  300.0 │
│ EMEA    │      2 │  165.7 │
│ APAC    │      2 │ 149.75 │
└─────────┴────────┴────────┘

$ duckdb -c "SELECT name FROM read_json_auto('users.json') WHERE active = true"

┌───────────────┐
│     name      │
│    varchar    │
├───────────────┤
│ Alice Martin  │
│ Chloé Bernard │
└───────────────┘

$ duckdb -c "SELECT order_id, region, amount, RANK() OVER (PARTITION BY region ORDER BY amount DESC) AS rank_in_region FROM 'orders.csv' ORDER BY region, rank_in_region"

┌──────────┬─────────┬────────┬────────────────┐
│ order_id │ region  │ amount │ rank_in_region │
│  int64   │ varchar │ double │     int64      │
├──────────┼─────────┼────────┼────────────────┤
│     1004 │ AMER    │  300.0 │              1 │
│     1002 │ APAC    │   89.0 │              1 │
│     1005 │ APAC    │  60.75 │              2 │
│     1001 │ EMEA    │  120.5 │              1 │
│     1003 │ EMEA    │   45.2 │              2 │
└──────────┴─────────┴────────┴────────────────┘

$ duckdb -c "SELECT r.manager, o.region, COUNT(*) AS orders, SUM(o.amount) AS total FROM 'orders.csv' o JOIN 'regions.json' r USING (region) GROUP BY ALL ORDER BY total DESC"

┌───────────────┬─────────┬────────┬────────┐
│    manager    │ region  │ orders │ total  │
│    varchar    │ varchar │ int64  │ double │
├───────────────┼─────────┼────────┼────────┤
│ Bruno Dupont  │ AMER    │      1 │  300.0 │
│ Alice Martin  │ EMEA    │      2 │  165.7 │
│ Chloé Bernard │ APAC    │      2 │ 149.75 │
└───────────────┴─────────┴────────┴────────┘
▋

Quatre types de requêtes vraiment différents, aucun n'a nécessité d'écrire un script : un GROUP BY/SUM sur le CSV, un filtre WHERE via read_json_auto sur le JSON, une fonction de fenêtrage RANK() OVER (PARTITION BY ...) et un JOIN entre le CSV et un fichier JSON, dans la même requête — le genre de question pour laquelle awk n'a tout simplement pas de réponse propre.

Ce qui rend DuckDB différent

DuckDB est un vrai moteur SQL — la syntaxe, le planificateur de requêtes, tout — sauf qu'il tourne dans le processus, n'a besoin d'aucun serveur et lit les fichiers CSV/JSON/Parquet directement comme s'il s'agissait de tables :

SELECT * FROM 'orders.csv';
SELECT * FROM read_json_auto('users.json');

Pas de CREATE TABLE, pas d'étape d'import, pas de schéma à définir — il déduit les types de colonnes en échantillonnant le fichier, la même idée que le parsing automatique de jq mais avec tout SQL par-dessus au lieu d'un langage de filtres.

Installation

À tester en deux minutes

Cliquez sur le bouton ci-dessous pour obtenir un script qui crée /tmp/duckdb-json avec le Dockerfile et les trois fichiers de démo :

Il n'existe pas de package apt ou pip pour le CLI DuckDB lui-même (seulement pour les bindings Python), donc le Dockerfile télécharge le binaire officiel de la release.

Rendre duckdb disponible partout

/tmp/duckdb-json servait seulement à la démo : il disparaît au prochain reboot. Ce qui doit rester sur votre PC, c'est le Dockerfile, pour que l'image puisse être reconstruite à tout moment (nouvelle machine, docker image prune, nouvelle version de DuckDB). Donnez-lui une place permanente dans ~/tools/duckdb, et construisez l'image depuis là :

mkdir -p ~/tools/duckdb
cp /tmp/duckdb-json/Dockerfile ~/tools/duckdb/
docker build -t duckdb-cli ~/tools/duckdb

Ce qui transforme cette image en commande, c'est une fonction, et elle a son propre fichier dans un dossier que votre shell charge au démarrage, la même organisation que dans mon workflow ZSH modulaire : votre fichier rc reste court, et supprimer l'outil revient à effacer un fichier.

Le code est le même pour zsh et bash ; seuls le dossier et le loader diffèrent.

for fn_file in ~/.zsh/fns/*.zsh; do
  source "$fn_file"
done

for fn_file in ~/.bash/fns/*.sh; do
  [[ -r "$fn_file" ]] && source "$fn_file"
done

Vérifiez que le shell connaît la fonction : type duckdb doit répondre duckdb is a shell function. Allez ensuite dans le dossier de démo et rejouez la première requête de cet article :

cd /tmp/duckdb-json
duckdb -c "SELECT region, COUNT(*) AS orders, SUM(amount) AS total FROM 'orders.csv' GROUP BY region ORDER BY total DESC"

Désormais, ça fonctionne pareil dans n'importe quel dossier contenant un fichier CSV ou JSON. La fonction monte le dossier courant comme /workspace, donc les chemins dans votre SQL sont relatifs à l'endroit où vous êtes. Ce dossier est monté en lecture seule sauf si le premier argument est --write ; --read-only de son côté verrouille le système de fichiers du container lui-même, pour que rien ne puisse être écrit dans l'image non plus ; un fichier hors du dossier courant n'est pas visible, faites d'abord un cd dessus. Sans argument, duckdb ouvre le shell SQL interactif ; avec -c "SQL", il exécute une requête et se termine ; du SQL envoyé par un pipe (cat report.sql | duckdb) fonctionne aussi.

Si l'image est absente, la fonction n'échoue pas sur une erreur Docker cryptique, elle vous explique comment la reconstruire depuis ~/tools/duckdb :

Error: the Docker image "duckdb-cli" does not exist on this machine.

How to continue:
  1. docker build -t duckdb-cli "${HOME}/tools/duckdb"
  2. Run your duckdb command again.

Et si ~/tools/duckdb/Dockerfile a disparu aussi, le message renvoie vers cet article pour le récupérer.

Utiliser duckdb

La console interactive

Une fois la fonction en place, taper duckdb sans argument ouvre une console SQL interactive, l'endroit le plus confortable pour jouer avec les deux instructions de Ce qui rend DuckDB différent :

$ duckdb
Read-only: your files cannot be modified. Start with "duckdb --write" to save files.
DuckDB v2.0.0 (Cyanoptera)
Enter ".help" for usage hints.
memory D SELECT * FROM 'orders.csv';
┌──────────┬─────────┬────────┐
│ order_id │ region  │ amount │
│  int64   │ varchar │ double │
├──────────┼─────────┼────────┤
│     1001 │ EMEA    │  120.5 │
│     1002 │ APAC    │   89.0 │
│     1003 │ EMEA    │   45.2 │
│     1004 │ AMER    │  300.0 │
│     1005 │ APAC    │  60.75 │
└──────────┴─────────┴────────┘
memory D SELECT * FROM read_json_auto('users.json');
┌───────────────┬────────────┬─────────┐
│     name      │ birth_date │ active  │
│    varchar    │    date    │ boolean │
├───────────────┼────────────┼─────────┤
│ Alice Martin  │ 1990-04-12 │ true    │
│ Bruno Dupont  │ 1985-11-02 │ false   │
│ Chloé Bernard │ 1998-07-23 │ true    │
└───────────────┴────────────┴─────────┘
memory D .quit

Regardez la seconde table : personne n'a rien déclaré, et pourtant birth_date revient en date et active en boolean, déduits des valeurs JSON elles-mêmes. Le prompt memory D signifie que la session tourne sur une base en mémoire jetable : un SELECT lit vos fichiers et ne change rien. .help liste les commandes de la console.

UPDATE et DELETE : lecture seule par défaut, --write quand c'est voulu

DuckDB exécute UPDATE et DELETE sur des tables, jamais sur un fichier lu directement : UPDATE 'orders.csv' SET … est refusé avec Can only update base table, quelles que soient les permissions. Modifier un fichier passe donc toujours par les trois mêmes étapes : le charger dans une table, modifier la table, la réécrire avec COPY ... TO.

Cette dernière étape est une écriture, et la fonction duckdb la refuse par défaut : elle monte le dossier courant en lecture seule, pour qu'aucune requête ne puisse altérer vos fichiers par accident. Mettez --write en premier pour l'autoriser :

$ duckdb -c "CREATE TABLE o AS FROM 'orders.csv'; UPDATE o SET amount = round(amount * 1.21, 2) WHERE region = 'EMEA'; DELETE FROM o WHERE region = 'APAC'; COPY o TO 'orders_fixed.csv'"

IO Error: Cannot open file "orders_fixed.csv": Read-only file system
Tip: the current folder is read-only. If this failed while writing a file, run it again as: duckdb --write ...

$ duckdb --write -c "CREATE TABLE o AS FROM 'orders.csv'; UPDATE o SET amount = round(amount * 1.21, 2) WHERE region = 'EMEA'; DELETE FROM o WHERE region = 'APAC'; COPY o TO 'orders_fixed.csv'"

$ cat orders_fixed.csv
order_id,region,amount
1001,EMEA,145.81
1003,EMEA,54.69
1004,AMER,300.0

Le orders.csv d'origine est intact ; orders_fixed.csv contient les montants EMEA avec 21 % de TVA et plus aucune row APAC. Écrivez plutôt dans 'orders.csv' et c'est le fichier lui-même qui est réécrit. COPY ... TO écrit du CSV, du JSON ('out.json') ou du Parquet ('out.parquet'), choisi d'après l'extension. Pour conserver des tables entre deux sessions au lieu d'une base en mémoire jetable, attachez un fichier de base de données, ce qui est aussi une écriture : duckdb --write, puis ATTACH 'shop.duckdb' AS shop;.

À retenir

Conclusion

Entre python-pandas-merge pour tout ce qui demande du vrai scripting, jq/awk/ai-data pour les one-liners rapides, et maintenant DuckDB pour tout ce qui se situe entre les deux et relève vraiment d'une question SQL, j'ai nettement arrêté de me dire « allez, un petit script Python ». Un fichier .csv et un fichier .json, interrogés et joints ensemble en une ligne de vrai SQL, sans serveur, sans import — voilà un outil qui mérite une place permanente dans mon ~/.zsh/fns/.

Ouvrez la liste des containers de Docker Desktop après quelques jours de travail en devcontainer et vous obtenez quelque chose comme serene_ganguly, objective_hopper, vigilant_tesla... Lequel est mon blog ? Lequel est mon projet PHP ?

Un nom aléatoire est aussi un vrai problème dès que vous voulez être générique : un script, un alias ou une commande docker exec ne peuvent pas cibler un container dont le nom change à chaque rebuild.

Avec un fichier compose.yaml, il suffirait de définir container_name: pour le container et la clé name: de premier niveau pour regrouper les services — voir Docker - Comment regrouper vos containers. Un devcontainer construit depuis un simple Dockerfile n'a ni l'une ni l'autre.

Il a mieux : runArgs.

Les deux lignes

runArgs est un tableau d'arguments supplémentaires que VS Code passe à docker run au moment de créer le container. N'importe quel flag de docker run y fonctionne, donc :

Reconstruisez le container (Dev Containers: Rebuild Container depuis la palette de commandes) et regardez à nouveau Docker Desktop.

--name : un nom de container stable

--name=docusaurus-devcontainer est l'équivalent, côté docker run, du container_name: d'un fichier compose. Le container s'appelle désormais toujours docusaurus-devcontainer, donc ceci fonctionne depuis n'importe quel terminal, à chaque rebuild :

docker exec -it docusaurus-devcontainer bash
docker logs --follow docusaurus-devcontainer

--label : le regroupement dans Docker Desktop

Docker Desktop ne regroupe pas les containers par magie : il lit le label com.docker.compose.project que Docker Compose pose sur chaque container qu'il crée. La clé name: d'un fichier compose.yaml n'est rien d'autre que la valeur de ce label.

Rien ne vous empêche de définir ce label vous-même. Avec --label=com.docker.compose.project=blog-devcontainer, le devcontainer rejoint le groupe blog-devcontainer dans Docker Desktop — et peut être arrêté en même temps que tout autre container portant le même label.

Choisissez la même valeur pour tout ce qui va ensemble, et gardez le suffixe -devcontainer : sur un vrai projet, le groupe blog contient les containers qui font tourner les services (une base de données, un reverse proxy, ...) tandis que blog-devcontainer contient les environnements dans lesquels vous codez. Un coup d'œil à Docker Desktop vous dit qui est qui, et arrêter un groupe n'arrête jamais l'autre.

Et si mon devcontainer utilise compose.yaml ?

Alors vous n'avez pas besoin de runArgs du tout (VS Code l'ignore dans ce mode de toute façon) : définissez container_name: sur le service et la clé name: de premier niveau dans le fichier compose, comme expliqué dans Docker - Comment regrouper vos containers.

runArgs est la réponse pour la configuration la plus courante : un devcontainer.json qui pointe vers une image ou un Dockerfile, comme dans Développement PHP dans un devcontainer avec des outils de qualité de code préinstallés.

Conclusion

Deux lignes dans devcontainer.json, et le serene_ganguly aléatoire devient docusaurus-devcontainer, bien rangé sous blog-devcontainer dans Docker Desktop. Je les ajoute maintenant à chaque nouveau devcontainer, juste après la clé name.

Windows affiche 2 Go libres. Rien côté Windows ne l'explique — pas de gros téléchargements, pas d'installation récente. Le coupable est un fichier qui n'apparaît pas dans l'analyse d'espace disque de l'Explorateur : docker_data.vhdx, le disque virtuel où Docker Desktop stocke tout ce qu'il construit.

docker system df révèle la situation réelle :

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          149       15        94.53GB   61.71GB (65%)
Containers      15        2         5.092GB   3.765GB (73%)
Local Volumes   67        41        26.76GB   4.667GB (17%)
Build Cache     2842      0         180.4GB   109.3GB (60%)

2 842 entrées de build cache, 180 Go, accumulées silencieusement au fil de mois d'utilisation normale de Docker.

Avant toute chose, vérifiez la taille réelle du fichier .vhdx sur le disque. Ouvrez PowerShell et lancez :

Get-ChildItem "$env:LOCALAPPDATA\Docker\wsl\disk\" -Filter "*.vhdx" |
    Select-Object Name, FullName, @{n='SizeGB';e={[math]::Round($_.Length/1GB,2)}}

Name               FullName                                                                SizeGB
----               --------                                                                ------
docker_data.vhdx   C:\Users\christophe\AppData\Local\Docker\wsl\disk\docker_data.vhdx     288.45

La colonne FullName donne le chemin exact dont vous aurez besoin à l'étape de compactage. SizeGB est le nombre à surveiller — 288 Go ici, pour un contenu Docker réel d'environ 90 à 110 Go.

Si le dossier disk\ est vide, ouvrez Docker Desktop → l'icône d'engrenage → Resources → Advanced : le champ Disk image location indique le dossier parent ; le VHDX se trouve un niveau plus bas, dans le sous-dossier disk.

Après le correctif

Une fois le cache nettoyé et le VHDX compacté, docker system df est propre :

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          149       15        94.53GB   61.71GB (65%)
Containers      15        2         5.094GB   3.765GB (73%)
Local Volumes   67        41        26.76GB   4.667GB (17%)
Build Cache     0         0         0B        0B

Et docker_data.vhdx, qui pesait 288 Go dans l'Explorateur Windows, est revenu à son contenu réel. L'Explorateur reflète le changement immédiatement après le compactage.

Pourquoi le prune seul ne suffit pas

Quatre faits expliquent l'écart entre « Docker a libéré 180 Go » et « Windows affiche toujours 2 Go libres » :

• WSL2 stocke toutes les données Docker dans un seul fichier .vhdx. Images, containers, volumes, build cache — tout vit dans docker_data.vhdx. Docker n'écrit pas directement sur C:\.
• Le VHDX ne fait que grossir. Quand Docker ajoute des données, le fichier grandit. Quand Docker supprime des données, les blocs sont marqués libres à l'intérieur du système de fichiers virtuel, mais le fichier .vhdx garde la même taille physique.
• docker builder prune libère des blocs ; il ne compacte pas le disque. Après le prune, 180 Go sont disponibles dans le système de fichiers virtuel. Windows voit toujours le même fichier de 288 Go.
• fstrim est le pont. Après un prune, les blocs libérés dans ext4 ne sont pas remis à zéro — ils sont simplement marqués non alloués dans le système de fichiers. La couche .vhdx n'a aucun moyen de savoir que ces blocs sont vides tant que fstrim ne le signale pas explicitement. Sans fstrim, l'étape de compactage ne trouve rien à supprimer et le fichier ne rétrécit pas.

Étape 1 — Vider le build cache

Lancez docker system df pour confirmer que la ligne Build Cache est bien le principal responsable, puis nettoyez-la :

docker builder prune -a -f

ID                                              RECLAIMABLE     SIZE            LAST ACCESSED
9v69gh88n3lsd778zxygzi6oj*                      true            11.6MB          2 months ago
ckqqh9pmzysj5bba2598kw58o*                      true            54.49MB         7 weeks ago
mrriwuzhxnbf09fvs6ezamzi6*                      true            15.51MB         2 months ago
[... 2839 more entries ...]
oneg7c4vr96xkpwb28nqgqwa6                       true            435.5MB         Less than a second ago
08or6idagqqm3fi66y48c3aft                       true            104.3MB         Less than a second ago
hq7jnob1j3bnb0n6nylra53a9                       true            113.5MB         Less than a second ago
cilxc42q905svkob16oiapvfd                       true            28.23MB         Less than a second ago
Total:  180.4GB

Le flag -a supprime toutes les entrées du cache, y compris celles qui pourraient encore accélérer un rebuild. Le flag -f saute la demande de confirmation.

Les images et les volumes peuvent eux aussi s'accumuler à côté du cache :

• docker image prune -a — supprime toute image non référencée par un container en cours d'exécution ou arrêté.
• docker container prune — supprime les containers arrêtés. Sans risque si vous utilisez --rm par défaut.
• docker volume prune — supprime les volumes qui ne sont attachés à aucun container.

Relancez docker system df pour confirmer que la ligne Build Cache affiche 0B avant de continuer.

Étape 2 — Indiquer au VHDX quels blocs sont libres (fstrim)

Docker sait que les blocs sont libres. Le .vhdx, non. fstrim perce des trous dans le disque virtuel, en signalant quels blocs sont désormais vides pour que l'étape de compactage puisse les supprimer physiquement :

docker run --rm --privileged --pid=host alpine nsenter -t 1 -m -- fstrim -av

Lancez ceci dans PowerShell ou Windows Terminal — pas dans WSL. La commande démarre un container, entre dans le namespace root de la VM Docker Desktop et exécute fstrim sur tous les systèmes de fichiers montés.

/parent-distro/mnt/host/wsl/docker-desktop-bind-mounts/Ubuntu-24.04/a3f7c91b2e8d05f634a8c7d9e1b4f2a8c6d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1: 987.1 GiB (1059882524672 bytes) trimmed on /dev/sdf
/mnt/docker-desktop-disk: 6.1 GiB (6548037632 bytes) trimmed on /dev/sdd
/parent-distro: 48 MiB (50331648 bytes) trimmed on /dev/sde

Étape 3 — Arrêter Docker et WSL

Sauvegardez votre travail en cours dans VSCode, puis quittez Docker Desktop depuis la zone de notification (clic droit → Quit Docker Desktop).

Attendez que le processus Docker Desktop ait complètement disparu :

Get-Process "Docker Desktop" -ErrorAction SilentlyContinue

Relancez cette commande jusqu'à ce qu'elle ne renvoie plus rien — une sortie vide signifie que le processus s'est terminé. Vérifiez ensuite WSL :

wsl --list --running

Si la liste n'est pas vide :

wsl --shutdown

La sortie attendue de wsl --list --running ensuite est There are no running distributions.

Compacter le VHDX — choisissez votre voie

Les étapes 1 à 3 sont les mêmes pour tout le monde. L'étape de compactage dépend de vos droits sur la machine.

J'ai rencontré ce problème sur mon portable professionnel, où je n'ai pas les droits admin local. Mon collègue IT a pris la main à distance et a lancé la séquence diskpart du chemin admin. Une fois déconnecté, j'ai suivi le chemin non-admin pour mettre en place les garde-fous — histoire que ça ne se reproduise pas.

J'ai les droits administrateur local

Vérifiez d'abord si le module PowerShell Hyper-V est disponible sur votre machine :

Get-Module -ListAvailable Hyper-V

Option A — Optimize-VHD (sans diskpart)

Si la commande a renvoyé une entrée de module :

Optimize-VHD -Path "C:\Users\your-name\AppData\Local\Docker\wsl\disk\docker_data.vhdx" -Mode Full

Sur certaines machines d'entreprise, Optimize-VHD exige quand même l'appartenance au groupe Hyper-V Administrators, même si le module est présent. En cas d'erreur « Access denied », passez à l'option B.

Option B — diskpart

Ouvrez un PowerShell élevé (clic droit → Exécuter en tant qu'administrateur), tapez diskpart puis lancez les quatre commandes une par une :

diskpart

select vdisk file="C:\Users\your-name\AppData\Local\Docker\wsl\disk\docker_data.vhdx"
attach vdisk readonly
compact vdisk
detach vdisk
exit

attach vdisk readonly ouvre le fichier en lecture seule — aucune donnée n'est modifiée. L'étape compact affiche un pourcentage de progression qui grimpe jusqu'à 100 %. Comptez de quelques minutes sur un NVMe rapide à plus d'une heure sur un gros disque lent.

Une fois le compactage terminé, le fichier .vhdx rétrécit et l'Explorateur affiche immédiatement les gigaoctets récupérés. Démarrez Docker Desktop : tout fonctionne exactement comme avant.

Je n'ai pas les droits administrateur local

Sans droits admin local, ni diskpart ni Optimize-VHD ne sont directement accessibles. Les deux approches ci-dessous partent du panneau Troubleshoot de Docker Desktop (icône d'engrenage → Troubleshoot) :

Si l'IT peut vous accorder cinq minutes, envoyez à votre collègue les quatre commandes diskpart du chemin admin ci-dessus accompagnées du chemin .vhdx exact obtenu à l'étape de diagnostic. La séquence est sûre et réversible : attach vdisk readonly ouvre le fichier en lecture seule, compact vdisk supprime les blocs vides, detach vdisk le relâche.

Sinon, le Reset to factory defaults de Docker Desktop supprime docker_data.vhdx et en crée un neuf. Avec sparseVhd=true déjà défini dans .wslconfig (voir la section Prévention), le nouveau fichier se compactera automatiquement à mesure que Docker libère de l'espace — ce qui en fait une opération unique.

Avant le reset — sauvegardez ce que vous ne pouvez pas reconstruire

Les volumes nommés contenant des données importantes :

docker volume ls
docker run --rm `
  -v <volume-name>:/data `
  -v C:\docker-backup:/backup `
  alpine tar czf /backup/<volume-name>.tar.gz -C /data .

Les images provenant de registries publics et les containers arrêtés n'ont pas besoin d'être sauvegardés — ils se reconstruisent en quelques minutes depuis leurs Dockerfiles. La seule exception est une image créée avec docker commit (modifications à l'exécution capturées sans Dockerfile) ; si vous en avez une, sauvegardez-la avec docker save <image>:<tag> -o backup.tar avant de continuer.

Lancer le reset

Docker Desktop → l'icône d'engrenage → Troubleshoot → Reset to factory defaults.

Après le reset, vérifiez que le nouveau .vhdx est bien sparse :

fsutil sparse queryflag "$env:LOCALAPPDATA\Docker\wsl\disk\docker_data.vhdx"

La sortie attendue est This file is set as sparse. Si elle indique toujours NOT set as sparse, c'est que sparseVhd=true ne s'applique pas au disque de données de Docker Desktop dans votre version — le prune hebdomadaire ci-dessous empêche le fichier de grossir, et un compactage ponctuel par l'IT (le chemin admin) reste possible si vous avez besoin de récupérer l'espace.

Restaurer vos données sauvegardées

docker load -i "C:\docker-backup\<image>.tar"

docker volume create <volume-name>
docker run --rm `
  -v <volume-name>:/data `
  -v C:\docker-backup:/backup `
  alpine tar xzf /backup/<volume-name>.tar.gz -C /data

Reconstruisez tout le reste avec docker compose up dans chaque dossier de projet.

Prévention

Le correctif fonctionne, mais sans action le .vhdx regrossit en quelques mois. Trois niveaux de défense, de l'immédiat au permanent.

1. Activer sparseVhd

Depuis WSL 1.3.17 (mi-2024), Microsoft a ajouté sparseVhd à .wslconfig :

[experimental]
sparseVhd=true

Éditez C:\Users\<your-name>\.wslconfig et ajoutez ces deux lignes. Un VHDX sparse rend automatiquement à Windows les blocs libérés au fur et à mesure que Docker les supprime — plus besoin de compactage manuel par la suite.

Ce réglage ne concerne que les disques nouvellement créés. Si votre docker_data.vhdx actuel n'est pas déjà sparse (vérifiez avec fsutil sparse queryflag), il n'a aucun effet dessus. Laissez quand même le réglage dans .wslconfig : après un reset usine ou l'ajout d'une nouvelle distribution WSL, le nouveau disque en profitera automatiquement.

2. Contrôle quotidien de la taille dans votre terminal

Ajoutez cette fonction à votre .bashrc ou .zshrc — elle affiche un avertissement d'une ligne à la première ouverture de terminal de la journée lorsque le .vhdx dépasse 150 Go :

Le fichier témoin daté dans ~/.cache/ garantit que le contrôle ne tourne qu'une fois par jour. Ajustez le seuil de 150 selon votre situation disque.

3. Prune automatique hebdomadaire via le Planificateur de tâches Windows

Le Planificateur de tâches Windows peut lancer docker builder prune automatiquement — une tâche au niveau utilisateur ne demande pas de droits admin. Ouvrez PowerShell avec votre compte habituel :

$action = New-ScheduledTaskAction `
    -Execute "powershell.exe" `
    -Argument '-NoProfile -NonInteractive -Command "wsl -e docker builder prune -a -f --filter ''until=168h''"'
$trigger = New-ScheduledTaskTrigger -Weekly -DaysOfWeek Monday -At "08:00"
Register-ScheduledTask -TaskName "Docker-Weekly-Prune" -Action $action -Trigger $trigger

wsl -e docker exécute la CLI docker dans votre distribution WSL par défaut : cette distribution doit donc avoir l'intégration WSL de Docker Desktop activée (icône d'engrenage → Resources → WSL integration) ; sinon la tâche échoue sans aucune erreur visible.

Le flag --filter "until=168h" conserve les entrées de cache de moins d'une semaine, préservant la vitesse de rebuild des projets actifs tout en supprimant tout ce qui est plus ancien.

Vérifier et gérer la tâche

Confirmez que la tâche est bien enregistrée :

Get-ScheduledTask -TaskName "Docker-Weekly-Prune"

Sortie attendue : State: Ready. Inspectez ensuite le déclencheur et l'action :

$task = Get-ScheduledTask -TaskName "Docker-Weekly-Prune"
$task.Triggers
$task.Actions

Lancez-la tout de suite pour tester :

Start-ScheduledTask -TaskName "Docker-Weekly-Prune"

Attendez 10 à 15 secondes le temps que WSL démarre et que Docker réponde, puis vérifiez le résultat :

Get-ScheduledTask -TaskName "Docker-Weekly-Prune" | Get-ScheduledTaskInfo |
    Select-Object LastRunTime, LastTaskResult, NextRunTime

LastTaskResult: 0 signifie succès. La valeur 267011 (SCHED_S_TASK_NOT_SCHEDULED) est la valeur par défaut de Windows avant la première exécution d'une tâche — ce n'est pas une erreur.

Pour ouvrir la tâche dans l'interface graphique du Planificateur de tâches :

Start-Process taskschd.msc

Cliquez directement sur Bibliothèque du Planificateur de tâches dans le panneau de gauche (pas sur un de ses sous-dossiers — la tâche se trouve à la racine \, pas dans GoogleSystem, Microsoft ou un sous-dossier d'entreprise). Le panneau central liste toutes les tâches de la racine ; trouvez Docker-Weekly-Prune, clic droit → Propriétés pour modifier le déclencheur ou la commande. L'onglet Historique montre chaque exécution passée et son code de sortie.

Petite remarque : si l'interface du Planificateur de tâches vous semble être une relique de l'ère Windows NT — dense, modale, rien là où on s'y attend — c'est parce qu'elle l'est, en gros. Les cmdlets PowerShell ci-dessus font le travail plus vite.

Pour faire passer la fenêtre de rétention de 7 à, disons, 14 jours :

$action = New-ScheduledTaskAction `
    -Execute "powershell.exe" `
    -Argument '-NoProfile -NonInteractive -Command "wsl -e docker builder prune -a -f --filter ''until=336h''"'
Set-ScheduledTask -TaskName "Docker-Weekly-Prune" -Action $action

Pour supprimer complètement la tâche :

Unregister-ScheduledTask -TaskName "Docker-Weekly-Prune" -Confirm:$false

Désormais, chaque lundi matin, la tâche se réveille, se connecte à WSL, vide du build cache tout ce qui a plus d'une semaine, et se termine — aucune action manuelle requise.

Savoir si fstrim reste nécessaire tient à une seule chose : lancez fsutil sparse queryflag "$env:LOCALAPPDATA\Docker\wsl\disk\docker_data.vhdx" dans PowerShell.

• This file is set as sparse — Windows rend automatiquement les blocs libérés au disque. fstrim n'est plus jamais nécessaire.
• NOT set as sparse — l'espace libéré reste dans le .vhdx mais Docker le réutilise pour les builds suivants. Le fichier ne grossit plus, Windows arrête de se plaindre, et c'est un résultat parfaitement stable. Un compactage manuel (étapes 2–3 plus le compactage) reste une option si vous voulez un jour rendre physiquement ces gigaoctets à Windows, mais ce n'est plus urgent.

En cas de problème

Wsl/Service/E_UNEXPECTED — le service WSL est bloqué

Cette erreur apparaît quand wsl --shutdown a été appelé alors que Docker Desktop était encore en train de s'arrêter. La solution est un redémarrage complet de Windows. Aucune commande WSL n'aidera à ce stade. Après le redémarrage, votre distribution démarre normalement.

Vérifier vos fichiers VHDX après un redémarrage

Vérifiez que les fichiers VHDX sont intacts avant de relancer Docker Desktop :

Get-ChildItem HKCU:\Software\Microsoft\Windows\CurrentVersion\Lxss |
  ForEach-Object { Get-ItemProperty $_.PSPath } |
  Select-Object DistributionName, BasePath

Pour le disque de données de Docker Desktop en particulier :

Get-Item "C:\Users\your-name\AppData\Local\Docker\wsl\disk\docker_data.vhdx" |
  Select-Object Name, @{n='SizeGB';e={[math]::Round($_.Length/1GB,2)}}

Une taille de fichier non nulle et un Docker Desktop qui démarre normalement confirment que rien n'est corrompu.

Conclusion

Le build cache Docker s'accumule silencieusement et Windows ne récupère jamais l'espace de lui-même. Trois étapes — prune, trim, shutdown — sont identiques pour tout le monde. La méthode de compactage dépend ensuite d'une seule question : avez-vous les droits admin local ? Avec les droits admin, diskpart ou Optimize-VHD compactent le fichier existant sur place. Sans droits admin, Reset to factory defaults dans Docker Desktop crée un .vhdx tout neuf — aucun droit IT nécessaire pour le reset lui-même, uniquement pour le compactage ponctuel si vous voulez éviter la perte de données. Dans les deux cas, sparseVhd=true et un prune hebdomadaire planifié empêchent le problème de revenir.

Pour une vue d'ensemble de ce qui s'accumule avant de décider quoi nettoyer, lazydocker affiche chaque container, image et volume d'un coup d'œil depuis un seul panneau de terminal. Les fonctions ZSH pour Docker que j'utilise au quotidien — dex, dstop, dnuke — rendent la question « qu'est-ce qu'on peut nettoyer sans risque ? » triviale : dnuke démonte tout, volumes compris, pour un projet terminé, en une seule commande. Et si le problème de disque est plus profond que le cache — c'est la distribution WSL elle-même qui doit migrer vers un disque plus grand — déplacer une distribution WSL vers un autre emplacement détaille la méthode export-import.

Votre blog est votre vitrine publique. Une faute de frappe qui traîne, une commande qui ne fonctionne plus, une API qui a changé — chaque lecteur qui tombe sur ce paragraphe vous coûte en crédibilité. Le problème, c'est que la plupart des lecteurs ne prendront pas la peine d'ouvrir une issue GitHub ou d'envoyer un email. Mais si vous rendez la chose vraiment triviale — un clic, là où ils se trouvent — un nombre surprenant le fera.

Cet article construit ce mécanisme de bout en bout.

Démonstration

Le widget est actif sur cette page même. Sélectionnez quelques mots de ce paragraphe avec votre souris (ou votre doigt sur un téléphone) : un popover apparaît juste sous la sélection, avec quatre types de feedback.

Le lecteur en choisit un, puis un petit formulaire lui permet d'ajouter un commentaire facultatif avant l'envoi. Le formulaire le dit clairement : c'est un signal à sens unique — le lecteur ne laisse pas d'email, donc personne n'attend de réponse.

De votre côté, chaque signalement atterrit dans un fichier JSON sur le serveur, vous recevez un email, et une page protégée par token liste tout, du plus récent au plus ancien, avec des compteurs par type :

Comment ça marche

La fonctionnalité se compose de deux moitiés indépendantes qui reprennent le schéma utilisé par le composant Reaction (votes like / dislike) :

Reader selects text
  └─ mouseup / touchend fires on <article>
       └─ popover shows 4 feedback-type buttons (phase: selecting)
            └─ reader picks a type → optional details form (phase: confirming)
                 └─ POST api/typo.php
                      └─ validates nonce, honeypot, rate limits, dedup
                           └─ writes typo-data.json
                                └─ emails admin (6h cooldown)

• Pas de base de données — les signalements sont ajoutés à un fichier JSON, sous verrou de fichier.
• Pas de service tiers — un simple script PHP posé à côté de vos fichiers statiques.
• Défense en profondeur — neuf couches indépendantes bloquent les bots, les floods et les doublons (détaillées à la fin, pour les curieux).
• SSR-safe — le composant ne rend rien tant que le lecteur n'a pas sélectionné de texte.

Partie 1 — L'API PHP

Pourquoi PHP ?

Docusaurus produit un site statique. Il n'a aucun runtime côté serveur. Si vous êtes sur un hébergement mutualisé (OVH, Infomaniak, o2switch…), un petit PHP script posé à côté de vos fichiers statiques est le backend le moins contraignant possible — pas de process Node à gérer, pas de container Docker, pas de démarrage à froid serverless.

Structure des fichiers sur le serveur

Le script

L'API répond à trois requêtes : GET distribue un nonce (et, avec ?admin=TOKEN, la liste complète des signalements), POST enregistre un signalement, OPTIONS répond au preflight CORS. Chaque POST traverse les neuf couches décrites dans la section sécurité, à la fin de cet article, avant que quoi que ce soit ne soit écrit.

Protéger les fichiers JSON

Sans la règle .htaccess livrée dans api/.htaccess, n'importe qui peut faire GET https://yourdomain.com/api/typo-data.json et lire tous les signalements.

Les secrets

Le fichier api/.env contient deux secrets. Générez-les avec :

openssl rand -hex 32   # IP_HASH_SALT
openssl rand -hex 32   # NONCE_SECRET▋

Partie 2 — Le composant React

La sécurité SSR d'abord

Docusaurus rend les pages côté serveur (Node.js) avant de les hydrater dans le navigateur. Tout code qui touche à window, document ou localStorage fera planter la passe SSR s'il s'exécute au niveau du module ou dans le corps du composant.

Les règles :

1. Tout accès au DOM se fait dans un useEffect — il ne s'exécute que dans le navigateur.
2. L'état est initialisé à "idle", pas à une valeur lue depuis le navigateur.
3. Le composant retourne null à l'état idle — pas de DOM, pas de mismatch SSR.

Machine à états

Six phases, linéaires avec une seule bifurcation :

idle
  └─ user selects text → selecting
       └─ user picks a feedback type → confirming
            └─ form submitted → submitting
                 ├─ success → done
                 └─ error   → error

done et error affichent un badge que l'on peut fermer et qui remet l'état à idle. selecting et confirming repassent à idle si l'utilisateur clique en dehors du popover. confirming propose un lien « changer » qui ramène à selecting.

Les helpers localStorage

Avant que le popover de sélection du type n'apparaisse, deux gardes côté client s'exécutent :

1. Rate limit — maximum 5 envois par navigateur et par heure. Les timestamps sont stockés dans un tableau JSON dans localStorage sous la clé "typo_reports". Les entrées de plus de 24 heures sont purgées à chaque écriture.

2. Déduplication — un hash FNV-1a de slug + "|" + lowercase(text) est stocké à côté du timestamp. Si le même texte a déjà été signalé depuis ce navigateur (quel que soit le type), le composant saute directement à done.

FNV-1a est utilisé plutôt que crypto.subtle.digest parce qu'il est synchrone, et le risque de collision est acceptable dans ce cas d'usage.

function fnv1a(str) {
  let hash = 0x811c9dc5;
  for (let i = 0; i < str.length; i++) {
    hash ^= str.charCodeAt(i);
    hash = (hash * 0x01000193) >>> 0;
  }
  return hash.toString(16);
}

Les types de feedback

Quatre types couvrent la grande majorité des problèmes qu'un lecteur peut remarquer :

const FEEDBACK_TYPES = [
  { id: "typo",       icon: "🔤", label: "Typo" },
  { id: "incorrect",  icon: "❌", label: "Incorrect" },
  { id: "outdated",   icon: "⏰", label: "Outdated" },
  { id: "suggestion", icon: "💡", label: "Suggestion" },
];

Ils sont affichés dans une grille 2×2. L'API PHP valide le champ type contre cette même whitelist — toute autre valeur renvoie un 400.

Capturer le contexte

Quand l'utilisateur sélectionne du texte, le composant enregistre ±100 caractères de texte environnant depuis article.innerText. Ce contexte est envoyé à l'API pour que vous puissiez localiser la phrase exacte sans ouvrir l'article :

const fullText = article.innerText || "";
const idx = fullText.indexOf(text);
contextRef.current = idx !== -1
  ? fullText.slice(Math.max(0, idx - 100), idx + text.length + 100)
  : "";

Positionnement du tooltip

Le popover apparaît juste sous la sélection. window.scrollY + rect.bottom + 8 le place 8px sous le bord inférieur du texte sélectionné. Pour éviter que le formulaire de 280px de large ne déborde du bord droit du viewport :

const left = Math.min(window.scrollX + rect.left, window.innerWidth - 296);

Le composant

Trois points à noter :

• touchend est enregistré en plus de mouseup pour que le widget fonctionne sur les appareils tactiles.
• handleTypeSelect exécute les vérifications de rate limit et de déduplication au moment du choix du type, pas à la sélection — cela évite de consommer un slot de rate limit quand l'utilisateur sélectionne simplement du texte pour le copier.
• Le paragraphe disclaimer (« Signal à sens unique — aucune réponse ne sera envoyée ») est volontaire : le dire explicitement évite la frustration.

Le module CSS utilise partout les propriétés personnalisées --ifm-* de Docusaurus, donc le widget suit votre thème et le mode sombre sans effort supplémentaire.

Partie 3 — L'intégration dans Docusaurus

C'est ici qu'intervient le swizzling de Docusaurus. Plutôt que de modifier directement le fichier du thème en amont, Docusaurus vous permet de copier n'importe quel composant du thème dans src/theme/ et de le surcharger. Si vous n'avez pas encore swizzlé BlogPostItem, lancez :

yarn swizzle @docusaurus/theme-classic BlogPostItem --wrap▋

Cela crée src/theme/BlogPostItem/index.js. Ouvrez-le et ajoutez :

Le garde isBlogPostPage est essentiel — sans lui, le composant se monterait aussi sur la page de liste du blog, où il n'y a pas d'élément article.

Partie 4 — Le dashboard admin

L'endpoint admin PHP (GET ?admin=TOKEN) renvoie du JSON brut. Plutôt que de lire cette réponse brute, une petite page React sur /typo-dashboard la présente dans un format lisible : elle aplatit tous les tableaux de signalements par slug en une seule liste triée du plus récent au plus ancien, et affiche des compteurs récapitulatifs par type en haut.

Le dashboard est protégé par token : il réutilise la même clé reactions_admin_token dans localStorage que le dashboard des réactions, donc vous ne vous authentifiez qu'une fois pour les deux.

Si vous avez une page d'accueil admin, ajoutez cette entrée à son tableau TOOLS dans src/pages/admin.js :

Créer le composant

Créez ces fichiers dans votre site Docusaurus, puis copiez api/.env.example vers api/.env et collez-y les deux secrets générés plus haut :

Montez ensuite le composant dans src/theme/BlogPostItem/index.js comme montré en partie 3.

Déploiement

L'API utilise declare(strict_types=1) et un type de retour never sur jsonError(), donc votre serveur doit tourner en PHP 8.1 ou plus récent :

php -v▋

Les trois fichiers JSON doivent être accessibles en écriture par le process du serveur web :

$ chmod 664 api/typo-data.json api/typo-ratelimit.json api/typo-notifications.json▋

Une fois déployé, vérifiez l'aller-retour complet avant d'annoncer la fonctionnalité :

Nettoyez après le test :

echo '{}' > api/typo-data.json
echo '{}' > api/typo-ratelimit.json
echo '{}' > api/typo-notifications.json

Conception de la sécurité — couche par couche (sautez si vous voulez juste que ça tourne)

Chaque POST traverse neuf couches indépendantes avant qu'un signalement ne soit écrit.

Couche 1 — CORS

Seuls https://www.yourdomain.com et http://localhost:3000 (dev) sont autorisés comme Origin. Toute autre origine reçoit un 403 silencieux. Les requêtes same-origin n'envoient pas d'en-tête Origin et passent.

Couche 2 — Whitelist des méthodes

L'API ne répond qu'à GET (nonce + admin), POST (envoi) et OPTIONS (preflight). Tout le reste reçoit 405 Method Not Allowed.

Couche 3 — Nonce HMAC

Sans cela, quiconque connaît l'URL de votre API peut envoyer des signalements arbitraires avec une simple commande curl. Le nonce est un token HMAC basé sur le temps :

$nonce = hash_hmac('sha256', floor(time() / 900) . '|typo-report', NONCE_SECRET);

Le token est valable pour la fenêtre de 15 minutes en cours et la précédente (pour éviter une expiration gênante quand un utilisateur récupère le nonce à la minute 14 et envoie à la minute 15). Il n'y a aucun stockage — le token s'auto-valide. Chaque POST doit inclure cette valeur dans son body.

Couche 4 — Validation des entrées, whitelist de types et honeypot

Le honeypot est un <input name="website"> caché, invisible pour les humains mais rempli par les bots. Si website !== "", l'API renvoie 200 OK sans rien stocker.

Les vraies entrées sont ensuite validées :

• slug — alphanumérique, tirets, slashes, 200 caractères max
• text — 3 à 150 caractères, Unicode imprimable uniquement (\P{C} — pas de caractères de contrôle)
• type — doit valoir typo, incorrect, outdated ou suggestion (toute autre valeur → 400)
• comment — facultatif, 300 caractères max, même filtre de caractères
• context — facultatif, 300 caractères max, trimmé

Couche 5 — Rate limit global

Une fenêtre glissante de 60 secondes avec un maximum de 20 requêtes toutes IP confondues. Cela protège des pics soudains. L'état de la fenêtre est stocké sous une clé __global__ dans typo-ratelimit.json, mis à jour dans un unique bloc LOCK_EX.

Couche 6 — Rate limits par IP

Deux limites suivies indépendamment :

• 10 signalements max par IP et par heure glissante
• 3 signalements max par IP, par article, par 24 heures

Les adresses IP ne sont jamais stockées en clair. Elles sont hashées avec un sel secret : hash('sha256', IP_HASH_SALT . $ip). À sens unique — vous ne pouvez pas retrouver l'IP d'origine — mais suffisamment cohérent pour agréger.

Le script lit REMOTE_ADDR, jamais X-Forwarded-For : sur un hébergement mutualisé, X-Forwarded-For peut être falsifié par le client, ce qui permettrait à une seule IP d'en usurper des milliers et de contourner les limites par IP.

Couche 7 — Déduplication

Un hash SHA-256 de slug + "|" + lowercase(text) est stocké dans text_hash sur chaque signalement. Avant l'écriture, les signalements existants pour ce slug sont parcourus. Si le hash existe déjà, l'API renvoie 200 OK sans rien stocker. Cela absorbe silencieusement les envois en double.

Couche 8 — Écritures sous verrou de fichier

PHP sur hébergement mutualisé est multi-process. Chaque écriture utilise fopen + flock(LOCK_EX) + ftruncate + rewind + fwrite + flock(LOCK_UN) + fclose. La vérification du rate limit et l'écriture se font dans le même verrou pour éviter les races TOCTOU.

Couche 9 — Throttle des emails

Vous ne voulez pas d'une boîte mail inondée si un article populaire récolte 50 signalements en une heure. Le système de notification consulte typo-notifications.json pour connaître le timestamp du dernier email par article. Un nouvel email n'est envoyé que si plus de 6 heures se sont écoulées depuis le précédent.

Limitations connues

Débordement du tooltip sur le bord gauche

Le clamp Math.min(left, window.innerWidth - 296) empêche le formulaire de 280px de sortir de l'écran à droite. Un débordement à gauche (sélection près du bord gauche sur des viewports très étroits) n'est pas géré.

NAT en hébergement mutualisé

Les utilisateurs derrière le même NAT (par exemple le Wi-Fi d'un bureau) partagent la même REMOTE_ADDR. Si trois personnes différentes du même bureau signalent des problèmes sur le même article en 24 heures, la quatrième sera bloquée par le rate limit. C'est un compromis acceptable vu la contrainte de l'hébergement mutualisé.

Conclusion

Les lecteurs n'ouvriront jamais une issue GitHub pour vous dire qu'une commande est obsolète — mais ils sélectionneront une phrase et cliqueront sur un bouton. Avec environ 250 lignes de PHP et 300 lignes de React, chacun de ces signaux arrive désormais dans votre boîte mail, avec la phrase exacte et son contexte, sans base de données ni service tiers.

L'architecture est volontairement simple : chaque morceau peut être compris, débogué et modifié en lisant un seul fichier. Si vous voulez aussi que vos lecteurs vous disent ce qu'ils ont aimé, le composant Reaction utilise exactement le même schéma PHP + JSON.

Si vous avez installé Open WebUI pour discuter avec Ollama et que vous n'êtes pas allé plus loin, vous utilisez environ 20 % de ce qui est disponible. Le reste se trouve dans les onglets et les menus qu'on ne remarque pas quand on veut juste poser une question.

Cet article reprend là où le guide d'installation d'Ollama s'arrêtait — en supposant qu'Ollama tourne en local et qu'Open WebUI est accessible sur le port 4000 (ou là où vous l'avez déployé).

Voir la chose en action

Open WebUI expose une API compatible OpenAI, protégée par une clé d'API personnelle. Ici, elle résume de vraies notes de réunion, appelée directement depuis un terminal :

$ export TOKEN="sk-..."

$ curl -s -H "Authorization: Bearer $TOKEN" http://localhost:4000/api/models | jq -r '.data[].id'
code-quality:latest
qwen2.5-coder:3b
qwen3-coder:30b
task-tiny:latest

$ export MODEL="qwen2.5-coder:3b"

$ curl -s -X POST http://localhost:4000/api/chat/completions \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{
      "model": "'"$MODEL"'",
      "messages": [
        {"role": "system", "content": "You summarize text in exactly 3 bullet points, focusing on decisions, numbers and deadlines."},
        {"role": "user", "content": "Infra meeting, September 24. Present: Sarah, Tom, Lea. Tom presented the staging database status: still on Postgres 12, end of life is near. Decision: migrate staging to Postgres 16, deadline October 15. Lea asked about backups: weekly is no longer enough, the team agreed to switch to daily backups starting today. Sarah got the budget approved: 4,200 EUR for an external contractor to help with the migration. Action: Tom writes the rollback plan and reviews it with Sarah before October 1. Coffee machine on floor 2 is broken again."}
      ]
    }' | jq -r '.choices[0].message.content'
- **Postgres Migration**: Staging database to migrate from Postgres 12 to Postgres 16 by October 15.
- **Backup Change**: Weekly backups replaced with daily backups starting today.
- **Budget Approval**: 4,200 EUR for an external contractor to help with migration.
▋

Remplacez qwen2.5-coder:3b par un des ids affichés par la seconde commande sur votre machine — la section sur le nom du modèle explique pourquoi. Trois puces, basées sur les chiffres et les dates réellement présents dans le texte — pas une reformulation générique. C'est exactement la requête qu'envoie la fenêtre de chat — la section sur les clés d'API plus bas montre comment obtenir le $TOKEN, et la section Tools empaquette le même prompt sous forme de Tool réutilisable.

- **Decision:** Migrer le staging de PostgreSQL 12 à PostgreSQL 16, échéance du 15 octobre.
- **Action:** Tom rédige un plan de remise en arrière pour une vérification avec Sarah avant le 15 octobre.
- **Budget:** Approuvé un budget de 4,200 EUR pour un contractor externe pour la migration.

Pourquoi ça marche

• Les presets de modèles sont une combinaison sauvegardée de modèle de base, system prompt et température — passer de « Code Reviewer » à « Brainstorm Partner » se fait dans une liste déroulante, sans retaper le contexte à chaque fois.
• Knowledge (RAG) indexe vos propres documents et y ancre les réponses, en citant le passage source — le modèle répond à partir de ce que vous lui avez donné, pas de ses données d'entraînement.
• La recherche web donne au modèle des informations actuelles, au-delà de sa date de coupure d'entraînement ; activable message par message ou par défaut dans un preset.
• Tools et Functions sont du code Python qui tourne dans le container — les Tools que le modèle peut appeler, et les Functions réservées aux admins (Pipes, Filters, Actions) qui étendent la plateforme elle-même.
• Les clés d'API permettent à n'importe quel script d'atteindre tout ce qui précède via un endpoint compatible OpenAI.

Ces cinq fonctionnalités sont réellement indépendantes ; elles partagent juste une fenêtre de chat. Ce ne sont pas cinq vues sur la même chose.

Rappel d'installation

Si Open WebUI ne tourne pas encore chez vous, voici le compose.yaml minimal ; la procédure complète, avec captures d'écran, se trouve dans la section Open WebUI du guide d'installation d'Ollama.

docker compose up -d
open http://localhost:4000

Le volume open-webui conserve toutes vos données — conversations, documents uploadés, modèles personnalisés, functions — au fil des redémarrages et des mises à jour du container. Ne l'oubliez pas.

Presets de modèles — même modèle Ollama, personas différents

Ollama n'a qu'un seul modèle qwen3-coder:30b. Mais vous voulez peut-être lui parler comme à un relecteur de code intransigeant à un moment, et comme à un partenaire de brainstorming juste après — avec des system prompts et des réglages de température différents pour chacun.

Workspace → Models → + New Model

Donnez-lui un nom (« Code Reviewer »), sélectionnez le modèle de base dans Ollama, puis configurez :

• System prompt : l'instruction qui cadre chaque conversation avec ce preset. Pour un relecteur de code : "You are a strict code reviewer. Focus on correctness, security, and maintainability. Point out issues directly. Do not suggest cosmetic changes."
• Temperature : basse (0.1–0.3) pour une sortie déterministe et structurée ; haute (0.7–0.9) pour les tâches créatives. La valeur par défaut est généralement 0.8.
• Context length : combien de tokens de l'historique de conversation inclure. L'augmenter permet au modèle de se souvenir de plus de choses dans une longue conversation, au prix de plus de VRAM.

Sauvegardez le preset. Il apparaît maintenant dans le sélecteur de modèle en haut de chaque chat. Vous passez de « Code Reviewer » à « Brainstorm Partner » ou « Explain Like I'm Five » aussi facilement que d'un onglet à l'autre.

Knowledge — du RAG sur vos documents locaux

Workspace → Knowledge → + New Knowledge

Une collection Knowledge est un groupe de documents qu'Open WebUI indexe et utilise pour ancrer ses réponses. Contrairement à un chat brut, les réponses d'une query RAG citent les passages précis dont elles sont issues. Si le Q&R sur documents est tout ce dont vous avez besoin, AnythingLLM est une alternative dédiée qui dialogue avec la même instance Ollama.

Ce que vous pouvez uploader

• des fichiers PDF (les documents scannés fonctionnent si le texte est extractible)
• des fichiers Markdown
• du texte brut, DOCX, XLSX
• des URL de pages web (Open WebUI récupère et indexe le contenu)

Workflow

1. Créez une collection Knowledge, par exemple « Project Documentation »
2. Uploadez vos documents (glisser-déposer dans la vue de la collection)
3. Attendez l'indexation — un indicateur de progression montre chaque fichier en cours de traitement
4. Dans un chat, cliquez sur le bouton + → Knowledge → sélectionnez votre collection
5. Posez vos questions : "What does the API authentication section say about token expiry?"

Open WebUI récupère les passages les plus pertinents et les inclut dans le contexte du modèle. Le modèle répond à partir de vos documents, pas de ses données d'entraînement — et cite le document et la section utilisés.

Cas d'usage concrets

• la documentation technique d'un projet sur lequel vous travaillez
• une collection de notes Markdown que vous voulez interroger
• un ensemble de specs PDF ou de RFC à recouper
• vos propres articles de blog (interroger vos propres écrits)

Intégration de la recherche web

Admin Panel → Settings → Web Search

Activez-la et choisissez un moteur de recherche. Les options incluent SearXNG (auto-hébergé — il s'accorde naturellement avec une installation locale d'Open WebUI), DuckDuckGo, Google, Brave et d'autres. Pour SearXNG, vous pointez vers l'URL de votre propre instance et aucune clé d'API n'est nécessaire.

Avec la recherche web active, vous pouvez l'activer message par message via l'icône de recherche dans la barre d'outils du chat, ou l'activer par défaut pour un preset de modèle. Quand elle est active, Open WebUI interroge le moteur de recherche, récupère les premiers résultats et inclut leur contenu dans le contexte du modèle — lui donnant des informations actuelles au-delà de sa date de coupure d'entraînement.

Tools et Functions — étendre Open WebUI avec Python

Open WebUI dispose de deux systèmes de plugins Python, gérés à deux endroits différents :

• Tools (Workspace → Tools) : des fonctions que le modèle peut décider d'appeler pendant un chat, comme les outils MCP. Tout utilisateur qui en a la permission peut en ajouter.
• Functions (Admin Panel → Functions) : des extensions de la plateforme elle-même, réservées aux admins, pour tous les utilisateurs. Leur type est déduit du nom de la classe :
  • les Pipes apparaissent comme un modèle sélectionnable et remplacent entièrement l'appel au modèle (appeler une API externe, chaîner des modèles, etc.)
  • les Filters modifient les messages à l'entrée ou à la sortie — pré-traiter votre prompt, post-traiter la réponse
  • les Actions ajoutent un bouton sous un message

Le plugin le plus simple est un Tool. En voici un qui encapsule un prompt de résumé — exactement celui qui se cache derrière la démo en début d'article :

Pour l'installer : Workspace → Tools → + New Tool → coller → Save.

Activez-le ensuite pour un chat avec le bouton + (ou attachez-le définitivement à un preset de modèle). Collez du texte, demandez un résumé, et le modèle appelle summarize, qui formule la requête selon le nombre de mots et la langue configurés.

Tools et Functions peuvent faire bien plus — interroger une base de données, appeler une API REST, lire des fichiers sur l'host — parce que ce sont du Python exécuté dans le container Open WebUI. Le pattern Valves (un modèle Pydantic) fournit des réglages configurables par l'admin, affichés dans le panneau de paramètres du plugin.

Clés d'API — appeler Open WebUI depuis vos scripts

L'appel curl en début d'article envoie Authorization: Bearer $TOKEN. Ce token est une clé d'API personnelle, et elle est désactivée par défaut. Trois interrupteurs séparent une installation fraîche d'une clé fonctionnelle.

1. Activer la fonctionnalité (admin)

Admin Panel → Settings → General → Authentication, activez Enable API Key, puis Save.

C'est l'interrupteur général : tant qu'il est éteint, personne — pas même un admin — ne peut générer de clé. Dans la même section, API Key Endpoint Restrictions permet de limiter les routes qu'une clé peut appeler (par exemple uniquement /api/models,/api/chat/completions).

2. Autoriser les utilisateurs à créer des clés (admin)

Les utilisateurs non-admin ont aussi besoin de la permission API Keys :

• Pour tout le monde : Admin Panel → Users → Groups → Default Permissions → Features Permissions, activez API Keys, puis Save.
• Pour quelques personnes seulement (recommandé) : Admin Panel → Users → Groups, créez ou sélectionnez un groupe, ajoutez les utilisateurs, puis Permissions → Features Permissions → API Keys.

3. Créer la clé (utilisateur)

Cliquez sur votre icône de profil (en bas à gauche) → Settings → Account. La ligne API keys n'est qu'un titre : les contrôles se trouvent sur la ligne juste en dessous, Secrets. Cliquez sur Show sur cette ligne, puis sur Create new secret key. Une fois la clé créée, Copy API Key la place dans votre presse-papiers ; elle commence par sk-.

$ export TOKEN="sk-..."
$ curl -H "Authorization: Bearer $TOKEN" http://localhost:4000/api/models

Une liste JSON de modèles signifie que la clé fonctionne. Une clé porte exactement les permissions de l'utilisateur qui l'a créée — elle voit les mêmes modèles, les mêmes collections Knowledge et les mêmes Tools — alors créez-la depuis un compte qui n'a pas plus de droits que ce dont le script a besoin.

4. Choisir un nom de modèle que l'API connaît

Le champ model d'une requête doit être l'id exact d'un modèle de votre instance — nom et tag compris. Tout le reste renvoie :

{"detail":"Model not found"}

Ce message n'a rien à voir avec la clé : il signifie que le nom envoyé n'est pas dans la liste. Affichez les ids valides — le filtre jq ne garde que le champ id de chaque entrée (voir L'utilitaire jq pour Linux si la syntaxe vous est inconnue) :

$ curl -s -H "Authorization: Bearer $TOKEN" http://localhost:4000/api/models | jq -r '.data[].id'

Copiez-en un dans MODEL, comme dans l'exemple en début d'article.

Sous le capot (passez si vous voulez juste l'utiliser)

Gestion des conversations

Quelques fonctionnalités qui rendent l'usage quotidien plus confortable :

Folders : organisez vos conversations dans des dossiers nommés (clic droit sur une conversation dans la barre latérale). Pratique quand vous maintenez des fils séparés pour différents projets.

Tags : taguez vos conversations pour les filtrer rapidement. La barre latérale a un filtre par tag en bas.

Partage de conversation : générez un lien partageable pour n'importe quelle conversation (l'icône de partage dans l'en-tête du chat). Utile pour montrer à un collègue l'échange exact sans copier-coller.

Regenerate : survolez n'importe quelle réponse du modèle et cliquez sur le bouton de régénération (les flèches circulaires) pour obtenir une réponse différente avec le même prompt et les mêmes réglages. Le modèle est stochastique — la température fait qu'un même prompt produit des sorties différentes.

Accéder à Open WebUI depuis d'autres appareils

Si Ollama tourne sur votre station de travail principale et qu'Open WebUI écoute sur le port 4000, les autres appareils de votre réseau local peuvent y accéder via http://your-ip:4000. L'article Accéder à Ollama depuis votre réseau local couvre la configuration réseau — Open WebUI se place devant Ollama, la même approche s'applique donc.

Pour du HTTPS sur le réseau local (utile si vous voulez utiliser les API caméra ou micro dans le navigateur), placez un reverse proxy comme Caddy devant Open WebUI.

Conclusion

La valeur d'Open WebUI se cumule à mesure que vous empilez ces fonctionnalités. Un preset de modèle avec le bon system prompt et la bonne température supprime la friction de réexpliquer votre contexte à chaque chat. Une base de connaissances RAG ancre les réponses dans vos vrais documents. La recherche web ajoute l'information actuelle. Tools et Functions ajoutent des capacités que le modèle de base n'a pas, et une clé d'API ouvre tout cela à vos scripts — l'appel de résumé en début d'article en est le plus petit exemple.

La fenêtre de chat n'est qu'un début — passez une après-midi dans Workspace et Settings, et vous découvrirez un environnement IA local réellement configurable, qui vaut le temps investi à le mettre en place correctement.

Mon usage de jq reste très basique ; je suis loin de savoir écrire une ligne avec group_by du premier coup. À chaque fois, c'est la même histoire : je dois bricoler (et perdre plusieurs minutes) juste pour obtenir ce que je veux — ou même… je ne sais même pas qu'une certaine fonctionnalité existe. Avec awk, c'est encore pire : je sais que ça existe et que c'est incroyablement puissant, mais la syntaxe est tout simplement impossible.

Démo — JSON

$ ai-data users.json

→ Analyzing users.json (json)...

ai-data >
  5/5 ────────────────────────────────
  Extract all user names from the JSON file
  Count how many active users exist in the file
  Display name and birth date for each user, separated by colon
> Group users by active status and count them
  Find names of users born in the 1990s

$ jq 'group_by(.active) | map({"active": .[0].active, "count": length})' users.json

[
  {
    "active": false,
    "count": 1
  },
  {
    "active": true,
    "count": 2
  }
]
▋

Cinq suggestions, listées par ce à quoi elles répondent — chacune construite sur les vrais noms de champs (active, birth_date, name) que le modèle a vus dans l'échantillon, pas sur des placeholders d'un tutoriel jq. En choisissant la quatrième dans fzf, ce filtre group_by exact s'est retrouvé sur mon prompt ; je l'ai lu, il avait l'air correct, j'ai appuyé sur Entrée.

Démo — CSV

$ ai-data orders.csv

→ Analyzing orders.csv (csv)...

ai-data >
  5/5 ────────────────────────────────
  Show order IDs and amounts for EMEA region only
  Calculate total sales amount across all orders
> Count orders by region and display in descending order
  Display all orders with amount greater than 100
  Show first 10 orders with all fields

$ awk -F, 'NR>1 {print $2}' orders.csv | sort | uniq -c | sort -nr

      2 EMEA
      2 APAC
      1 AMER
▋

Le modèle a remarqué tout seul que region est la colonne intéressante pour un regroupement, et a répondu avec le classique pipeline awk | sort | uniq -c — le genre de ligne que je reconnais quand je la vois mais que je n'écris jamais de mémoire. L'avoir lue une fois sur mon propre prompt, je la comprends mieux que si j'avais juste vu la sortie.

L'idée — des suggestions, pas des réponses

La plupart des fonctions de cette série posent une question au modèle et affichent la réponse — ai-diagram affiche un bloc Mermaid, prêt à coller. ai-data est différente volontairement : elle demande au modèle des commandes candidates, les présente via fzf, et quand vous en choisissez une, elle ne l'exécute pas — elle la dépose sur votre prompt, modifiable, grâce au print -z de zsh. Vous lisez le filtre jq ou le script awk exact avant qu'il ne touche vos données, et comme c'est vous qui appuyez sur Entrée, vous assimilez vraiment la syntaxe au lieu de simplement consommer la sortie.

La fonction ai-data

Pas besoin de copier quoi que ce soit pour l'instant : les fichiers .zsh montrés dans cet article sont là pour être lus, et L'installer à la fin les crée tous dans ~/.zsh/fns/ pour vous.

Étape par étape :

1. Détecter JSON ou CSV à partir de l'extension.
2. Construire un petit échantillon réel — pour le JSON, les 3 premiers éléments s'il s'agit d'un tableau (jq -c '.[0:3]') ; pour le CSV, l'en-tête plus 5 lignes. Jamais le fichier entier : un CSV de 50 000 lignes n'a pas besoin d'en laisser plus de quelques-unes dans le prompt.
3. Pour le CSV, vérifier si mlr (Miller) est installé — si oui, on indique au modèle qu'il peut proposer mlr pour les regroupements/agrégations, ce qui se lit nettement mieux que l'équivalent awk. Sinon, il s'en tient à awk/sort/uniq.
4. Demander exactement 5 commandes, une par ligne, au format COMMAND ||| description — délibérément pas une sortie JSON, car parser cinq lignes de « texte avant un triple pipe » est trivial et évite le risque que le modèle emballe sa réponse dans des blocs Markdown ou ajoute des commentaires.
5. Envoyer les cinq lignes dans fzf, en n'affichant que la description (--with-nth=2) pour que vous choisissiez par intention, et non en plissant les yeux sur de la syntaxe jq.
6. À la sélection, print -rz du premier champ de la commande choisie.

Enregistrée dans le menu ai

Une ligne — AI_COMMANDS[data]=... — accessible via ai data <file> ou directement avec ai-data, aux côtés de toutes les autres fonctions de la série.

_ollama_query et le registre AI_COMMANDS vivent dans la fondation partagée _ollama.zsh introduite dans ai-test. Si vous avez déjà suivi un article précédent de cette série, elle est déjà dans ~/.zsh/fns/ et sourcée par votre autoloader — rien de plus à faire. Vous commencez ici ? C'est un des fichiers créés dans L'installer plus bas.

Points clés

L'installer

Tout tourne sur votre machine : zsh, curl et jq (qui construit la requête envoyée à Ollama), et un serveur Ollama joignable — voyez installer Ollama si vous n'en avez pas encore.

1. Créez les fichiers. Chaque fonction de cette série vit dans son propre fichier dans ~/.zsh/fns/. La commande ci-dessous crée ce dossier et les deux fichiers d'un coup — ou téléchargez le ZIP, ou créez chaque fichier à la main et collez-y son contenu. _ollama.zsh est la fondation partagée par toute la série : si un article précédent vous l'a déjà donnée, la copie ici est le même fichier.

2. Chargez le dossier depuis ~/.zshrc. Déjà fait si vous avez suivi un article précédent de cette série. Sinon, ajoutez ces lignes à la fin de ~/.zshrc — elles sourcent chaque fichier .zsh du dossier, donc la prochaine fonction que vous ajouterez ne demandera aucun changement ici :

for fn_file in ~/.zsh/fns/*.zsh; do
  source "$fn_file"
done

3. Ouvrez un nouveau terminal (ou lancez exec zsh dans celui en cours), et vérifiez que le shell connaît la nouvelle fonction :

type ai-data

ai-data is a shell function from …/ai-data.zsh signifie que vous êtes prêt. ai-data not found signifie que l'étape 2 manque.

Conclusion

ai-data est la fonction de cette série dont j'attends le plus en termes d'apprentissage, justement parce qu'elle refuse de me donner une réponse toute faite — elle me donne la commande et me laisse être celui qui la lance. Quelques semaines à piocher des filtres jq dans une liste fzf et à les lire avant d'appuyer sur Entrée, et je soupçonne que j'en aurai moins besoin qu'aujourd'hui. Ce serait une forme étrange de succès pour un outil d'IA : l'objectif n'est pas de l'utiliser pour toujours, c'est de se rendre discrètement moins nécessaire, un group_by à la fois.

Vous avez un compose.yaml avec dix services. Vous voulez savoir quelle image utilise le service db sans ouvrir d'éditeur. Vous voulez incrémenter un numéro de version dans un fichier CI sans une one-liner sed que vous ne retiendrez jamais. Vous voulez extraire tous les noms de services dans une liste.

Ce sont des problèmes pour jq. Mais vos fichiers sont en YAML, pas en JSON.

Voici yq.

Ce qu'est yq — et lequel

Il existe deux outils nommés yq. Cet article traite de yq de Mike Farah (Go, image Docker mikefarah/yq), qui gère nativement YAML et offre une syntaxe compatible jq. L'autre (kislyuk/yq) encapsule jq après avoir converti le YAML en JSON — idée similaire, comportement différent pour les fonctionnalités propres à YAML comme les commentaires et les fichiers multi-documents. Sur Debian et Ubuntu, apt install yq installe cet autre outil (kislyuk/yq 3.x), pas celui utilisé ici.

Si vous avez la version Go installée localement (yq --version renvoie quelque chose comme yq (https://github.com/mikefarah/yq/) version v4.x), tout est prêt. Sinon, l'approche Docker ci-dessous ne demande rien de plus.

Le voir à l'œuvre avec Docker

Avant d'installer quoi que ce soit (ou même de mettre en place l'alias ci-dessous), essayez yq dans un container jetable — le compose.yaml exact de cet article s'y trouve déjà.

Buildez et lancez :

$ docker build -t yq-demo .
[+] Building 8.7s (7/7) FINISHED
✔ exporting to image
$ docker run --rm -it yq-demo
🐳 root ~/demo # yq '.services.web.image' compose.yaml
nginx:1.25

Même fichier, même query, même résultat — testez directement dessus le reste des sections « Lire des valeurs » et « Modifier sur place » ci-dessous, il n'y a plus rien à préparer.

Installer — ou juste créer un alias

Un gestionnaire de packages installe la version Go sur toutes les plateformes :

$ brew install yq            # macOS and Linux (Homebrew)
$ winget install MikeFarah.yq  # Windows

Ne rien installer du tout est aussi une option : une petite fonction yq lance l'image officielle à la place, dans son propre fichier placé dans un dossier que votre shell charge au démarrage (l'organisation expliquée dans mon workflow ZSH modulaire) :

Elle monte votre répertoire courant dans le container et exécute yq de façon transparente, avec votre propre ID utilisateur pour que les fichiers modifiés avec -i gardent leur propriétaire. Toutes les commandes yq ci-dessous fonctionnent avec elle telles quelles. Le code est identique pour zsh et bash ; seuls le dossier et le chargeur diffèrent.

for fn_file in ~/.zsh/fns/*.zsh; do
  source "$fn_file"
done

for fn_file in ~/.bash/fns/*.sh; do
  [[ -r "$fn_file" ]] && source "$fn_file"
done

Vérifiez que le shell connaît la fonction : type yq doit répondre yq is a shell function.

La page des releases propose aussi des binaires statiques pour Linux, macOS et Windows — sans aucune dépendance à l'exécution.

Lire des valeurs

Travaillons avec un compose.yaml typique :

Lire une valeur unique :

yq '.services.web.image' compose.yaml

nginx:1.25

Lire une valeur imbriquée :

yq '.services.db.environment.POSTGRES_DB' compose.yaml

myapp_db

Lister tous les noms de services :

yq '.services | keys' compose.yaml

- web
- db

Récupérer toutes les images de tous les services :

yq '.services.*.image' compose.yaml

nginx:1.25
postgres:16

Filtrer et sélectionner

Récupérer uniquement les services qui définissent une clé ports :

yq '.services | with_entries(select(.value | has("ports")))' compose.yaml

web:
  image: nginx:1.25
  ports:
    - "8080:80"
  ...

Lister tous les noms de variables d'environnement du service web :

yq '.services.web.environment | keys' compose.yaml

- APP_ENV
- LOG_LEVEL

Modifier sur place

Mettre à jour la version de l'image web. Le flag -i modifie le fichier sur place, exactement comme sed -i :

yq -i '.services.web.image = "nginx:1.27"' compose.yaml

Ajouter une nouvelle variable d'environnement :

yq -i '.services.web.environment.DEBUG = "false"' compose.yaml

Supprimer une clé :

yq -i 'del(.services.db.environment.POSTGRES_PASSWORD)' compose.yaml

Lire depuis stdin et chaîner les commandes

yq lit depuis stdin quand aucun fichier n'est fourni, ce qui facilite le chaînage avec d'autres commandes :

cat compose.yaml | yq '.services | keys'

Combinez-le avec curl pour parser des API ou des configs YAML téléchargées à la volée :

curl -s https://example.com/config.yaml | yq '.database.host'

Cas d'usage pratiques

Extraire tous les mappings de ports

yq '.services.*.ports[]' compose.yaml

8080:80

Vérifier qu'une clé existe avant de l'utiliser

yq '.services | has("redis")' compose.yaml

false

Mettre à jour une version dans tout un fichier CI

Pour un .gitlab-ci.yml qui référence une version d'image à plusieurs endroits, .. parcourt chaque nœud du fichier, quelle que soit sa profondeur :

yq -i '(.. | select(. == "node:20")) = "node:22"' .gitlab-ci.yml

Merger deux fichiers YAML

yq '. *= load("overrides.yaml")' base.yaml

Cette commande fusionne en profondeur overrides.yaml dans base.yaml et affiche le résultat — les fichiers source restent inchangés, sauf si vous ajoutez -i.

Convertir du YAML en JSON

Quand vous devez passer des données YAML à un outil qui n'accepte que du JSON :

yq -o json '.services.web' compose.yaml

{
  "image": "nginx:1.25",
  "ports": [
    "8080:80"
  ],
  "environment": {
    "APP_ENV": "production",
    "LOG_LEVEL": "info"
  },
  "volumes": [
    "./html:/usr/share/nginx/html:ro"
  ],
  "depends_on": [
    "db"
  ]
}

Vous pouvez ensuite envoyer cette sortie directement à jq pour la traiter davantage.

Le pont avec jq

Si vous utilisez déjà jq pour JSON, la syntaxe de yq vous semblera immédiatement familière. Les expressions jq du quotidien fonctionnent telles quelles :

Les principales différences : yq ajoute -i pour les modifications sur place et -o pour le format de sortie, et gère les fonctionnalités natives de YAML comme les ancres et les fichiers multi-documents (séparateurs ---).

Conclusion

yq comble le manque que tout utilisateur de jq finit par ressentir : le même outil, mais pour YAML. Avec un alias Docker, il n'y a rien à installer, et la syntaxe se transpose directement depuis tout ce que vous connaissez déjà. Si votre workflow implique des compose.yaml, GitLab CI, GitHub Actions ou des manifests Kubernetes, yq a sa place dans votre boîte à outils aux côtés de jq et de son équivalent XML, xmlstarlet.

La prochaine fois que vous ouvrirez un éditeur de texte pour vérifier une version d'image ou modifier une clé de configuration, utilisez plutôt yq.

J'ai écrit plus d'articles « transformer X en diagramme » que je ne le croyais : Diagrams as code, un graphe à partir de compose.yaml, la documentation as code avec Python et Mermaid. Tous partagent la même forme : un vrai parser lit une entrée structurée et une librairie dessine l'image. Ça fonctionne très bien — jusqu'au moment où ce que je veux représenter est un paragraphe que je viens de taper, ou un fichier de config ponctuel qui ne mérite pas qu'on lui écrive un parser.

Démo — une description en langage naturel

$ ai-diagram "a user submits a contact form, the API validates the payload, saves it to Postgres, then sends a confirmation email via SMTP"

```mermaid
flowchart TD
    A[User submits contact form] --> B[API validates payload]
    B -->|Validation fails| C[Return validation errors]
    B -->|Validation passes| D[Save to Postgres]
    D --> E[Send confirmation email via SMTP]
    E --> F[Email sent successfully]
```
Preview: https://mermaid.live/edit#base64:eyJjb2RlIjoiZmxvd2NoYXJ0IFREXG4gICAgQVtVc2VyIHN1Ym1pdHMgY29udGFjdCBmb3JtXSAtLT4gQltBUEkgdmFsaWRhdGVzIHBheWxvYWRdXG4gICAgQiAtLT58VmFsaWRhdGlvbiBmYWlsc3wgQ1tSZXR1cm4gdmFsaWRhdGlvbiBlcnJvcnNdXG4gICAgQiAtLT58VmFsaWRhdGlvbiBwYXNzZXN8IERbU2F2ZSB0byBQb3N0Z3Jlc11cbiAgICBEIC0tPiBFW1NlbmQgY29uZmlybWF0aW9uIGVtYWlsIHZpYSBTTVRQXVxuICAgIEUgLS0-IEZbRW1haWwgc2VudCBzdWNjZXNzZnVsbHldIn0
▋

Pas de YAML, pas de schéma, juste une phrase — et un flowchart qui se ramifie sur la validation, la seule étape de cette phrase dont l'issue décide de la suite, tandis que l'enregistrement et l'envoi restent de simples étapes. Collé dans cette page, le bloc s'affiche ainsi :

Démo — un fichier de config existant

$ ai-diagram compose.yaml

```mermaid
graph TD
  app["app · build · :8080"]
  db["db · postgres:16"]
  cache["cache · redis:7"]
  db_data[("db-data")]

  app -- "depends_on" --> db
  app -- "depends_on" --> cache
  db -- "volumes" --> db_data
```
Preview: https://mermaid.live/edit#base64:eyJjb2RlIjoiZ3JhcGggVERcbiAgYXBwW1wiYXBwIMK3IGJ1aWxkIMK3IDo4MDgwXCJdXG4gIGRiW1wiZGIgwrcgcG9zdGdyZXM6MTZcIl1cbiAgY2FjaGVbXCJjYWNoZSDCtyByZWRpczo3XCJdXG4gIGRiX2RhdGFbKFwiZGItZGF0YVwiKV1cblxuICBhcHAgLS0gXCJkZXBlbmRzX29uXCIgLS0-IGRiXG4gIGFwcCAtLSBcImRlcGVuZHNfb25cIiAtLT4gY2FjaGVcbiAgZGIgLS0gXCJ2b2x1bWVzXCIgLS0-IGRiX2RhdGEifQ
▋

Trois services, leurs liens de dépendance et le volume nommé — lus directement dans la structure du fichier compose, avec chaque image et chaque port publié intégrés au label de son service :

D'autres phrases à essayer

Trois descriptions de plus, chacune prête à copier dans votre propre terminal. Chaque lien ouvre le diagramme produit par ai-diagram, dans le Mermaid Live Editor.

Tri des tickets de support

ai-diagram "When a customer submits a support ticket, check if it is urgent. If it is urgent, assign it directly to a senior agent. If it is not urgent, place it in the standard queue and send an automated confirmation email to the customer."

Voir le diagramme obtenu sur mermaid.live

Connexion avec verrouillage de compte

ai-diagram "To log into the system, the user enters their username and password. If the credentials are correct, grant access and display the main dashboard. If the credentials are incorrect, check if the attempt count is less than three. If it is less than three, increment the counter and ask the user to try again. Otherwise, lock the account and send a password reset link to the user's email."

Voir le diagramme obtenu sur mermaid.live

Une commande e-commerce

ai-diagram "When receiving an e-commerce order, first verify if the requested item is in stock. If it is out of stock, notify the customer and ask if they want to backorder or cancel. If they cancel, process a full refund. If the item is in stock, check if the payment is processed successfully. If payment fails, prompt the user to update their payment method. If payment succeeds, pack the order, generate a shipping label, ship the item, and send a tracking number to the customer."

Voir le diagramme obtenu sur mermaid.live

Sa place réelle à côté de docker-python-mermaid

La fonction ai-diagram

Pas besoin de copier quoi que ce soit pour l'instant : les fichiers .zsh montrés dans cet article sont là pour être lus, et L'installer à la fin les crée tous dans ~/.zsh/fns/ pour vous.

Deux modes d'entrée, distingués par un seul test — si le premier argument est un fichier existant, c'est un fichier :

1. Un fichier — lu tel quel, et le prompt demande au modèle de déduire le type de diagramme du contexte (un compose.yaml implique un graphe de services, un listing de dossier implique un arbre, une spec OpenAPI implique un diagramme de séquence). Une courte liste de règles garde le graphe honnête : un nœud par entité, une arête par relation, les attributs comme une image ou un port dans les labels, le stockage dessiné comme un cylindre.
2. Du texte libre — tout ce qui suit la commande est traité comme la description, et le modèle choisit lui-même le type de diagramme Mermaid le plus adapté, en ajoutant une branche d'échec uniquement là où une étape est elle-même une vérification (une validation, une connexion, un paiement) — jamais un « email envoyé ? » inventé sur une action simple.

Dans les deux cas, la sortie est un bloc ```mermaid et rien d'autre. Le prompt demande exactement ça, et _ai_strip_fences ne conserve ensuite que les lignes du bloc avant que la fonction ne les réencadre elle-même — de sorte que même une réponse qui commence par « Here is your diagram: » ressort prête à coller dans un article, où ce blog la rend nativement.

Avant de la coller quelque part, vous voudrez la voir. La dernière ligne, Preview: https://mermaid.live/edit#base64:…, ouvre le diagramme dans le Mermaid Live Editor avec un Ctrl+clic depuis le terminal — rendu, et modifiable si le modèle s'est trompé sur un label. L'éditeur lit tout son état dans la partie de l'URL après le # : le JSON {"code": "…"}, encodé en base64url, donc jq et base64 suffisent à le construire. Ce fragment n'est jamais envoyé au serveur dans la requête ; le diagramme est décodé et dessiné par la page, dans votre navigateur. Le lien part sur stderr, donc ai-diagram compose.yaml > docs/services.md n'écrit toujours rien d'autre que le bloc Mermaid.

Enregistrée dans le menu ai

Deux lignes — AI_COMMANDS[diagram]=... et AI_PARAMS[diagram]="text" — la rendent accessible via ai diagram <input> ou directement via ai-diagram, aux côtés de toutes les autres fonctions de la série. Choisie depuis le menu ai seul, elle demande son entrée : tapez une description, ou un nom de fichier.

_ollama_query, _ai_strip_fences et le registre AI_COMMANDS vivent tous dans la fondation partagée _ollama.zsh présentée dans ai-test. Si vous avez déjà suivi un article précédent de cette série, elle se trouve déjà dans ~/.zsh/fns/ et est sourcée par votre autoloader — rien de plus à faire. Vous commencez ici ? C'est l'un des fichiers créés dans L'installer plus bas.

À retenir

L'installer

Tout tourne sur votre machine : zsh, curl et jq (qui construit la requête envoyée à Ollama), et un serveur Ollama accessible — voyez installing Ollama si vous n'en avez pas encore.

1. Créez les fichiers. Chaque fonction de cette série vit dans son propre fichier dans ~/.zsh/fns/. La ligne de commande ci-dessous crée ce dossier et les deux fichiers d'un coup — sinon téléchargez le ZIP, ou créez chaque fichier à la main et collez son contenu. _ollama.zsh est la fondation partagée par toute la série : si un article précédent vous l'a déjà donnée, la copie ici est le même fichier.

2. Chargez le dossier depuis ~/.zshrc. Déjà fait si vous avez suivi un article précédent de cette série. Sinon, ajoutez ces lignes à la fin de ~/.zshrc — elles sourcent chaque fichier .zsh du dossier, donc la prochaine fonction que vous ajouterez ne nécessitera aucun changement ici :

for fn_file in ~/.zsh/fns/*.zsh; do
  source "$fn_file"
done

3. Ouvrez un nouveau terminal (ou lancez exec zsh dans celui en cours), et vérifiez que le shell connaît la nouvelle fonction :

type ai-diagram

ai-diagram is a shell function from …/ai-diagram.zsh signifie que vous êtes prêt. ai-diagram not found signifie que l'étape 2 manque.

Conclusion

Mes articles doc-as-code ont toujours supposé que j'avais déjà quelque chose de structuré à donner à un parser. ai-diagram comble le vide en amont — la phrase que je viens de taper, le fichier que j'ai mais pour lequel je n'ai pas écrit de parser. Il ne remplacera pas Diagrams as code ni docker-python-mermaid pour ce qui doit être exact et reproductible, mais pour le cas « laisse-moi juste esquisser ça vite fait » qui signifiait avant d'ouvrir un outil de whiteboard, c'est devenu une commande et un collage.

Vous avez remplacé grep par ripgrep. Vous êtes à peu près sûr que c'est plus rapide. Mais de combien ? La différence est-elle réelle ou n'est-ce qu'un effet de cache lié au premier run ?

Vous avez optimisé une étape de build Docker. Vous pensez que c'est mieux. Mais vous ne l'avez chronométrée qu'une fois, avec time, qui vous donne un seul point de mesure et aucune statistique.

hyperfine répond correctement à ces questions.

Un premier benchmark

Comparons grep -r et git grep pour trouver tous les TODO d'un repository. Les deux sont déjà sur votre machine, et git grep ne cherche que dans les fichiers suivis par git :

hyperfine --warmup 3 'grep -r "TODO" .' 'git grep "TODO"'

Benchmark 1: grep -r "TODO" . (10 runs)
                mean     ±       σ          min     …     max
  Wall Time    321.4 ms  ±     7.0 ms     315.6 ms  …   335.2 ms
  Memory        11.5 MiB ±     0.0 MiB     11.5 MiB …    11.6 MiB

Benchmark 2: git grep "TODO" (29 runs)
                mean     ±       σ          min     …     max
  Wall Time    102.3 ms  ±     1.9 ms      99.7 ms  …   106.4 ms           -68.2%  (3.1x faster)
  Memory        31.8 MiB ±     0.8 MiB     29.6 MiB …    33.0 MiB         +176.1%  (2.8x more)

Moyenne, écart-type, min, max — pour le temps et la mémoire, sur autant de runs que nécessaire pour obtenir des chiffres stables. Chaque commande après la première est comparée à la première : ici git grep est 3,1 fois plus rapide, et utilise 2,8 fois plus de mémoire pour y arriver.

Installation

Avec Homebrew (macOS, Linux et WSL) :

brew install hyperfine

Avec cargo (toolchain Rust) :

cargo install hyperfine

Avec apt (Debian, Ubuntu) :

sudo apt install hyperfine

curl -LO https://github.com/sharkdp/hyperfine/releases/download/v2.0.0/hyperfine-musl_2.0.0_amd64.deb
sudo apt install ./hyperfine-musl_2.0.0_amd64.deb

Vérification :

hyperfine --version

hyperfine 2.0.0

Les runs de warmup

Le premier run d'une commande est souvent plus lent : les caches disque sont froids, l'OS n'a rien préchargé. C'est ce qui rend peu fiables les outils à mesure unique comme time. hyperfine gère ça avec --warmup :

hyperfine --warmup 3 'grep -r "TODO" .' 'rg "TODO"'

Trois runs jetables avant le début de la mesure. Le benchmark ne chronomètre que l'état chaud — la condition qui compte en usage réel.

Contrôler le nombre de runs

Par défaut, hyperfine exécute chaque commande au moins 10 fois, et continue pendant au moins trois secondes — c'est pourquoi les commandes rapides obtiennent des centaines de runs. Vous pouvez surcharger ce comportement :

hyperfine --min-runs 20 'my-command'   # at least 20 runs
hyperfine --runs 5 'my-command'        # exactly 5 runs (faster, less accurate)

Pour les commandes lentes (builds Docker, compilation), utilisez moins de runs :

hyperfine --runs 3 'docker build -t myapp:v1 -f Dockerfile.v1 .'

Pas de shell par défaut

Depuis la version 2.0, hyperfine exécute chaque commande directement, sans shell intermédiaire. Cela retire le temps de démarrage du shell de la mesure, mais cela signifie aussi que la syntaxe shell — pipes, redirections, &&, ~ — n'est pas interprétée. hyperfine refuse une telle commande plutôt que de mesurer silencieusement la mauvaise chose :

$ hyperfine 'seq 100 | sort'
Error: Command 'seq 100 | sort' contains unquoted shell syntax ('|').
Explicitly choose how to execute it:
-S / --shell=default  Interpret shell syntax.
-N / --shell=none     Run directly, passing '|' as a literal argument.

Ajoutez -S pour exécuter la commande via sh, ou --shell bash / --shell zsh pour en choisir un. Vos alias et fonctions shell ne sont jamais disponibles, avec ou sans -S : hyperfine ne voit que de vrais exécutables.

Benchmarker avec des entrées variables

Utilisez des placeholders {var} combinés à --parameter-list. Le pipe ci-dessous nécessite un shell, d'où le -S :

hyperfine -S --parameter-list size 100,1000,10000 

'seq {size} | sort'

Benchmark 1: seq 100 | sort (1870 runs)
                mean     ±       σ          min     …     max
  Wall Time    569.5 µs  ±   209.2 µs     393.0 µs  …  1907.6 µs
  Memory         1.7 MiB ±     0.1 MiB      1.6 MiB …     1.9 MiB

Benchmark 2: seq 1000 | sort (2920 runs)
                mean     ±       σ          min     …     max
  Wall Time    700.3 µs  ±   321.8 µs     396.0 µs  …  2185.2 µs           +23.0%
  Memory         2.1 MiB ±     0.2 MiB      1.9 MiB …     2.4 MiB          +21.6%

Benchmark 3: seq 10000 | sort (1949 runs)
                mean     ±       σ          min     …     max
  Wall Time   1081.8 µs  ±   336.0 µs     840.7 µs  …  2630.4 µs           +89.9%  (1.9x slower)
  Memory         2.6 MiB ±     0.1 MiB      2.4 MiB …     2.8 MiB          +52.4%  (1.5x more)

Cela lance trois benchmarks automatiquement et vous montre comment la performance évolue avec la taille de l'entrée. Pour des commandes aussi courtes, hyperfine affiche aussi un avertissement : en dessous de 5 ms, le temps de démarrage du shell pèse sur le résultat.

Préparation et nettoyage

Certains benchmarks ont besoin d'une étape de setup qui ne doit pas être mesurée — vider un cache, créer un fichier de test, réinitialiser un état. Utilisez --prepare :

hyperfine --prepare 'sync; echo 3 | sudo tee /proc/sys/vm/drop_caches' 

'grep -r "function" /usr/lib/python3'

La commande --prepare est exécutée avant chaque run chronométré, sans faire partie du temps mesuré. Elle passe toujours par un shell, donc le ; et le pipe fonctionnent ici sans -S.

Exporter les résultats

Trois formats d'export sont les plus utiles :

Table Markdown (à coller directement dans un article de blog ou un README) :

hyperfine --export-markdown results.md 'find . -name "*.md"' 'grep -rl "TODO" .'

La table ne contient que la métrique principale — le wall time, sauf si vous en choisissez une autre avec --metrics :

| Command | Mean Wall Time [ms] | Change | Factor |
|:---|---:|---:|:---|
| `find . -name "*.md"` | 6.2 ± 0.2 |  |  |
| `grep -rl "TODO" .` | 33.9 ± 0.8 | +446.7% | (5.5x slower) |

CSV (pour les tableurs ou une analyse plus poussée, une colonne par métrique) :

hyperfine --export-csv results.csv 'command1' 'command2'

JSON (pour le scripting, avec chaque run individuel) :

hyperfine --export-json results.json 'command1' 'command2'

Exemples concrets

grep vs ripgrep — le battage est-il justifié ?

hyperfine --warmup 3 

'grep -r "ERROR" /var/log' 

'rg "ERROR" /var/log'

Deux stratégies de build Docker

Vous avez un Dockerfile monolithique et une version multi-stage. Laquelle build le plus vite à partir d'un cache froid ?

hyperfine --runs 3 

'docker build --no-cache -t test:mono -f Dockerfile.mono .' 

'docker build --no-cache -t test:multi -f Dockerfile.multi .'

Le flag --no-cache garantit que chaque run repart de zéro. Sans lui, le cache de layers de Docker rend le deuxième run quasi instantané, quelle que soit la stratégie.

Temps de démarrage du shell

Si vous optimisez votre ~/.zshrc (peut-être après avoir lu l'article sur les workflows ZSH modulaires), mesurez l'impact avant et après :

hyperfine --warmup 5 

'zsh -i -c exit' 

'bash -i -c exit'

Comparaison des alternatives à find

hyperfine --warmup 3 

'find . -type f -name ".ts"' 

'fd -t f -e ts' 

'rg --files -g ".ts"'

fd est rarement installé par défaut : brew install fd, ou sudo apt install fd-find sur Debian et Ubuntu, où la commande s'appelle fdfind.

Cela compare trois outils sur 10 runs ou plus chacun — impossible à évaluer équitablement avec un chronomètre.

Interpréter la sortie

Les chiffres clés :

• Wall Time, moyenne ± σ : temps moyen et écart-type. Un σ élevé par rapport à la moyenne signifie que les résultats varient beaucoup — plus de runs ou un --prepare pour vider les caches aideraient.
• min … max : le run le plus rapide et le plus lent. Un écart important suggère des interférences externes (autres processus, I/O).
• Memory : le pic mémoire utilisé par la commande. Pratique quand l'outil le plus rapide est aussi le plus gourmand.
• La colonne de comparaison : chaque benchmark après le premier est comparé au premier, en pourcentage et sous la forme « N.Nx faster » ou « slower ». C'est le chiffre que vous êtes venu chercher — mettez donc votre commande de référence en premier.

Sous le capot (passez votre chemin si vous voulez juste l'utiliser)

hyperfine vs time

La commande intégrée time vous donne une mesure. C'est très bien pour une curiosité ponctuelle. hyperfine sert quand le résultat compte :

Si vous présentez un benchmark à une équipe, rédigez un article de blog ou prenez une décision basée sur des données de performance, utilisez hyperfine. Pour une vérification rapide au feeling, time suffit.

Conclusion

hyperfine rend les affirmations de performance testables. ripgrep est-il plus rapide que grep ? Votre étape de build refactorisée est-elle vraiment une amélioration ? L'alias eza que vous avez ajouté à la place de ls se remarque-t-il ? Ce sont des questions auxquelles hyperfine répond en quelques secondes, avec assez de rigueur statistique pour faire confiance au résultat.

Ajoutez-le à votre boîte à outils, à côté des outils que vous benchmarkez déjà, et arrêtez de deviner.

Je publie deux fois par semaine, le lundi et le jeudi, et ça dure depuis un bon moment. Quelque part autour du billet numéro 150, je n'ai plus été capable de répondre à des questions que j'aurais dû connaître par cœur : cet article sur fzf, est-il seulement lié depuis quelque part ? Quel est le billet vers lequel tout le reste renvoie ? Est-ce que toute la série Quarto s'est retrouvée isolée du reste du blog ?

J'avais les données — le frontmatter de chaque article, chaque lien inline — mais aucun moyen de les regarder. Une liste de 262 lignes, ce n'est pas une façon de regarder quoi que ce soit.

J'ai donc construit /map — une page qui dessine le blog sous forme de graphe. Voici comment ça fonctionne et comment en construire une.

Ce que la page carte vous montre

Chaque article publié est une bulle. Plus elle est grosse, plus d'autres articles pointent vers elle. Des lignes relient les billets réellement liés entre eux — survolez-en un et tout ce qui n'est pas son voisin direct s'estompe :

┌─ Blog Map ──────────────────────────────────────────────────────────────────┐
│                                                                             │
│  Filter by topic  [ Top 120 most-linked articles  ▾ ]                       │
│  262 articles · 25 series · 680 internal links                              │
│                                                                             │
│                           Running Docusaurus with Docker                    │
│         ·   ·                     ●                                         │
│       ·  ╲  │ ╱  ·               ╱ ╲                                        │
│     ·──── (◉) ────·             ●   ●───────● Docker-out-of-Docker          │
│       ·  ╱  │ ╲  ·               ╲ ╱                                        │
│         ·   ·                     ●                                         │
│                                                       🦫                    │
│                                              (drawn bigger than its size:   │
│                                               nothing links to this one yet)│
│                                                                             │
│  ▸ View as list instead                                                     │
└─────────────────────────────────────────────────────────────────────────────┘

Trois choses à faire sur cette page :

• Filtrer par sujet avec la liste déroulante pour restreindre le graphe à un seul mainTag. Les articles qui partagent le tag mais ne sont liés à rien autour d'eux restent visibles — c'est exactement le genre d'orphelin que vous ne remarqueriez jamais autrement.
• Survoler un nœud pour voir son titre et mettre en évidence ses connexions directes. Un cluster qui paraît dense de loin se révèle souvent être deux ou trois hubs avec beaucoup de satellites qui ne pointent que vers l'intérieur.
• Passer en liste en bas de page si vous préférez le texte au canvas, ou si vous avez désactivé JavaScript : chaque article est toujours là, groupé par série, entièrement indexé.

Pourquoi calculer le layout au build change tout

Un graphe force-directed, c'est normalement une affaire de navigateur : vous embarquez une bibliothèque physique, vous y déposez les nœuds et vous les regardez se stabiliser pendant quelques secondes. Cette approche échoue sur trois exigences qui comptaient vraiment pour moi, et déplacer la simulation dans Node règle les trois d'un coup.

• La page doit fonctionner sans JavaScript. Si les positions sont déjà finales dans le HTML, la seule chose qu'ajoute JavaScript est le dessin — le chemin sans JS peut donc retomber sur une liste simple, rendue côté serveur et entièrement indexable, de tous les articles, au lieu d'une boîte vide.
• Rien ne doit s'animer tout seul. Il n'y a pas de branche prefers-reduced-motion à écrire, parce qu'il n'y a aucun mouvement à supprimer : le graphe est déjà au repos à l'instant où il apparaît.
• d3-force n'atteint jamais le lecteur. Il reste une dépendance de build. Le navigateur reçoit des nombres, pas un solveur.
• Le même build produit la même carte. L'ordre des nœuds est trié avant le démarrage de la simulation, et d3-force place les nœuds à partir de leur index de tableau plutôt que de Math.random() : un rebuild sans changement de contenu reproduit exactement la même image.

Le coût de tout ça, c'est une seconde de plus dans yarn build. C'est le meilleur arbitrage que j'aie fait sur ce blog.

La construire

Deux morceaux : un plugin qui calcule le graphe, et un composant qui le dessine.

Le plugin

Il lit le corpus via le même loader que celui déjà utilisé par mon outillage de tags, construit les arêtes, colore chaque nœud, exécute 300 ticks de simulation et passe le résultat à setGlobalData :

L'exécuter en standalone montre à quoi ressemble la charge utile :

$ node --input-type=module -e "
import('./plugins/blog-graph-plugin/index.mjs').then(async m => {
  const graph = await m.default().loadContent();
  const byType = {};
  for (const edge of graph.edges) byType[edge.type] = (byType[edge.type] ?? 0) + 1;
  console.log('nodes  ', graph.nodes.length);
  console.log('edges  ', graph.edges.length, byType);
  console.log('meta   ', graph.meta);
  console.log('payload', JSON.stringify(graph).length, 'bytes');
});"

nodes   262
edges   1026 { link: 680, series: 144, tag: 202 }
meta    { articleCount: 262, seriesCount: 25, linkCount: 680 }
payload 183292 bytes

262 nœuds, 1026 arêtes, 179 Ko de JSON — calculés une fois au build, plus jamais touchés par le navigateur.

Une décision mérite d'être soulignée : les couleurs des nœuds ne sont pas une nouvelle palette. Un billet appartenant à une série réutilise la couleur d'accent de cette série depuis src/data/series.js — la même que celle dont la page des séries habille son hero. Un billet sans série retombe sur la couleur d'accent extraite automatiquement de son image de bannière. Seul un billet qui n'a ni l'un ni l'autre obtient un gris neutre. La carte ressemble donc au reste du site gratuitement, et un lecteur qui reconnaît déjà « la bleue, c'est la série Quarto » la reconnaît ici aussi.

Le composant

BlogGraph lit ces données globales, les dessine sur un <canvas> et se remplace par une liste simple en dessous de 768px :

Canvas, pas SVG, et ce n'est pas une préférence esthétique : 262 nœuds plus un millier d'arêtes en éléments DOM, et chaque survol devient un recalcul de layout sur un millier de nœuds. Sur un canvas, un survol, c'est un redessin complet de quelques centaines de formes, autant dire rien.

Enregistrez le plugin dans docusaurus.config.js et donnez-lui une page :

plugins: [
  "./plugins/blog-graph-plugin/index.mjs",
  // ...
],

---
title: "Blog Map"
description: "An interactive map of the whole blog."
hide_table_of_contents: true
---

import BlogGraph from "@site/src/components/BlogGraph";

<BlogGraph />

Les trois types de connexion

Une arête signifie « ces deux billets sont liés », mais la parenté a des intensités, et les mélanger à poids égal produit une pelote de laine. Mon corpus émet trois types, chacun avec sa propre traction sur le layout :

La ligne tag est l'endroit où se cache l'échec intéressant. À cette taille de corpus, presque chaque paire de billets partage au moins un tag — les relier toutes reviendrait à tout relier à tout et détruirait à la fois le layout et l'image. Monter la barre à deux tags partagés laisse encore 1 355 paires, dont 1 153 sont du type le plus faible possible :

shared tags:   2      3     4    5
pairs:       1153    159    40    3

Le plugin fait donc deux choses différentes avec cet ensemble. Le layout utilise toutes les paires jusqu'à deux tags partagés, parce que cette faible traction spatiale est précisément ce qui regroupe « tous mes billets Docker ». La charge utile n'embarque que les paires à trois tags ou plus, parce que rien ne dessine jamais le reste — embarquer la majorité à poids 2 aurait triplé le JSON pour des lignes invisibles. Mêmes données, deux seuils, un pour la physique et un pour le réseau.

Sous le capot (passez si vous voulez juste la carte)

Quatre problèmes qui n'étaient pas évidents avant que la page soit réellement à l'écran.

Un filtre à deux nœuds donnait un canvas géant et vide

Choisissez un sujet de niche dans le filtre et vous obtiendrez peut-être trois articles. Le canvas, lui, restait dimensionné pour 120. Mon premier correctif a été de le dimensionner selon le ratio d'aspect de la bounding box des nœuds visibles — ce qui a échoué, parce que deux articles partageant un mainTag ne sont pas obligés d'être proches dans le layout partagé calculé sur tout le corpus. Deux nœuds aux extrémités opposées produisent un ratio extrême qui revient directement se caler sur la hauteur maximale.

Le deuxième signal, le nombre de nœuds relatif à la vue par défaut, attrape ce cas mais écraserait un cluster réellement haut et compact. computeCanvasHeight() calcule donc les deux et garde le plus petit. Aucun des deux angles morts ne peut produire un canvas surdimensionné à lui seul :

const ratio = contentAspectRatio(nodes) ?? maxRatio;
const aspectHeight = clamp(Math.round(containerWidth * ratio) + padding);

const density = Math.min(nodes.length / defaultTopN, 1);
const densityHeight = clamp(
  Math.round(minHeight + (maxHeight - minHeight) * Math.sqrt(density)),
);

return Math.min(aspectHeight, densityHeight);

Des libellés qui s'empilent les uns sur les autres

Dessiner 262 titres est illisible : seuls les huit nœuds visibles les plus connectés gardent un libellé permanent, auxquels s'ajoutent le nœud survolé et ses voisins directs. Même ça s'empile quand un sujet filtré est chargé. selectNonOverlappingLabels() parcourt les candidats par ordre de priorité — le nœud survolé d'abord, puis les voisins, puis les hubs — mesure chacun avec ctx.measureText() et écarte tout libellé dont la boîte croiserait une boîte déjà placée. Les libellés les moins prioritaires perdent ; celui du nœud survolé gagne toujours.

Un canvas n'entend pas un changement de thème

Les couleurs des nœuds et des arêtes sont lues depuis les variables CSS du site, pour que rien ne soit en dur — mais un canvas est un bitmap, et basculer en mode sombre ne repeint rien. La solution : un MutationObserver sur l'attribut data-theme de <html> qui incrémente un compteur, lequel figure dans le tableau de dépendances de l'effet de redessin :

useEffect(() => {
  const observer = new MutationObserver(() => setThemeVersion((v) => v + 1));
  observer.observe(document.documentElement, {
    attributes: true,
    attributeFilter: ["data-theme"],
  });
  return () => observer.disconnect();
}, []);

Les suricates

Ce blog a une mascotte — elle se cache dans le code source de la page, chevauche le bouton de retour en haut et apparaît sur la page 404. Sur la carte, ce n'est pas une garniture sur quelques nœuds : chaque bulle est un suricate, portant le sticker que lui a valu son mainTag. Les articles PHP tiennent un petit éléphant violet, les articles Bash portent un sweat à capuche, code-quality arrive avec une coche verte. Une trentaine de tags ont un sticker explicite et le reste en tire un de façon déterministe parmi ce qui reste, si bien qu'un sujet a toujours la même tête et que ses articles se lisent comme une famille sur le canvas.

Ce qui fait marcher tout ça, ce sont les images, pas le code : ce sont des portraits carrés, centrés sur le visage. Les poses en pied avec lesquelles j'avais commencé perdaient leur tête dans un recadrage circulaire de 20px, il a donc fallu les choisir et les recadrer une par une ; un portrait centré survit à un simple dessin « cover » sans réglage image par image.

Deux règles empêchent que ça tourne à la bouillie :

• un sticker a besoin de place. En dessous de 12px de diamètre, l'anneau mange un tiers de l'image et un point coloré plat en dit davantage — c'est donc ce que gardent ces nœuds.
• un orphelin est dessiné plus gros. Un nœud avec zéro connexion visible se retrouve au rayon minimal, c'est-à-dire juste sous ce seuil. Il obtient un plancher de 13px à la place, pour que l'unique article vers lequel rien ne pointe soit celui que vous ne pouvez pas rater.

L'anneau autour de chaque bulle conserve la couleur d'accent de l'article, donc rien du signal série/tag n'est perdu au profit de l'illustration.

Conclusion

La carte a fait exactement ce que j'espérais : cinq minutes après son premier rendu, j'avais la liste des billets vers lesquels rien ne pointait, et je voyais qu'une série avait dérivé loin de tout le reste. C'est un outil de maintenance déguisé en jolie image.

La partie qui mérite d'être reprise, pourtant, ce n'est pas le graphe — c'est l'endroit où le travail se fait. Chaque exigence dure de cette page (pas de JavaScript, pas de mouvement, indexable, charge utile légère) s'est dissoute à l'instant où la simulation est passée du navigateur à loadContent(). Les plugins Docusaurus tournent dans Node, avec tout le corpus sous la main et une étape de build que personne n'attend ; ça laisse beaucoup de marge pour calculer les choses correctement, une fois, plutôt que de demander au portable de chaque visiteur de recommencer.

La prochaine fois que vous êtes sur le point d'attraper une bibliothèque côté client, vérifiez si la réponse qu'elle calcule n'aurait pas pu être une constante dans votre sortie de build.

Il existe un embarras particulier, réservé aux gens qui construisent seuls. J'avais passé des semaines sur des fonctionnalités dont j'étais sincèrement fier : une carte interactive de tout le blog, un index de questions généré par un modèle local, une palette de commandes à six modes.

Puis je me suis posé une question plus simple que d'habitude : comment un lecteur qui n'est jamais venu ici trouverait-il l'index de questions ? Il y avait exactement deux portes d'entrée. Appuyer sur Ctrl+K, puis ? pour basculer la palette en mode question — ce qui suppose de connaître à la fois le raccourci et l'existence du mode. Ou aller sur /faq, ce qui suppose de savoir que la page existe.

Les deux portes étaient ouvertes. Les deux ne fonctionnaient que pour quelqu'un qui avait déjà lu l'article les annonçant, c'est-à-dire : moi.

Ce qui a changé

Deux choses, dont aucune n'est une nouvelle fonctionnalité :

1. A floating bubble              2. A first-visit pill
   ┌────────────────┐               ┌─────────────────┐
   │ 🦫 Ask my blog │               │ Press ⌘K to     │
   ├────────────────┤               │ search      ✕   │
   │ [Ask a questi…]│               └─────────────────┘
   │  › How do I …  │                 once per browser,
   │  › What is …   │                 then never again
   └────────────────┘
     bottom-right, every page

La bulle est la plus intéressante, parce qu'elle est la troisième voie vers exactement le même index de questions : Ctrl+K puis ?, la page autonome /faq, et maintenant un bouton en forme de chat qui suit le lecteur partout. Même corpus, même classement, mêmes résultats — trois portes.

Pourquoi trois portes, ce n'est pas de la redondance

J'ai résisté à la bulle un moment, au motif que la palette faisait déjà le travail. C'était une erreur, et voici le raisonnement qui m'a fait changer d'avis :

• Chaque porte sert un lecteur différent. La palette sert ceux qui savent déjà qu'elle existe. /faq sert les moteurs de recherche et les gens qui veulent parcourir un sujet. La bulle sert le lecteur bloqué au milieu d'un article, qui n'aurait jamais l'idée d'appuyer sur un raccourci clavier.
• Un bouton flottant est la seule affordance que tout le monde comprend déjà. Personne n'a besoin qu'on lui explique ce que fait une bulle de chat dans un coin. C'est précisément pour ça qu'elle mérite un coin — et pourquoi l'en-tête du panneau arbore la même mascotte suricate qu'on retrouve partout ailleurs sur ce site.
• Ça ne coûte presque rien à ajouter. La bulle ne réimplémente pas la recherche — elle monte le composant de recherche existant dans un panneau. Environ 150 lignes, dont l'essentiel est de la gestion du focus.
• La partie chère était déjà payée. Le corpus de questions, le classement, le chargement paresseux : tout existait. Ajouter un point d'entrée à une fonctionnalité déjà construite est le travail au meilleur rapport effort/résultat, et c'est celui qu'on saute.

Ce raisonnement a une limite, et il vaut mieux l'énoncer avant d'aller ajouter une quatrième porte. Le test n'est pas « combien de points d'entrée puis-je caser ? » mais « celui-ci atteint-il un lecteur que les autres ratent ? ». J'avais aussi prévu une tuile en page d'accueil pointant vers la palette, et je l'ai abandonnée : la barre de navigation affiche déjà un champ de recherche visible en permanence, avec le raccourci imprimé dedans, sur chaque page. Trois portes pour trois lecteurs différents, oui. Trois rappels de la même porte, non.

Construire la bulle

Le composant est volontairement mince. Quand le panneau est fermé, rien de lié à la recherche n'est monté — le corpus de questions de 468 Ko n'est donc téléchargé que par un lecteur qui l'ouvre vraiment :

Il est monté une fois par page, dans le même swizzle Layout qui monte la palette :

export default function LayoutWrapper(props) {
  return (
    <Layout {...props}>
      {props.children}
      <CommandPalette />
      <CommandPaletteHint />
      <AskMyBlogWidget />
    </Layout>
  );
}

Une décision de mise en page à copier : la bulle réserve un emplacement fixe empilé au-dessus du coin occupé par le bouton de retour en haut, plutôt que de détecter la présence de ce bouton à l'exécution. Le retour en haut n'est pas monté sur toutes les pages, et un peu d'espace vide au-dessus quand il est absent est totalement inoffensif — bien plus inoffensif que deux boutons flottants se disputant les mêmes 60 pixels.

Le problème des deux overlays

La palette et le panneau de la bulle sont des dialogues flottants indépendants, chacun ouvrable depuis plusieurs endroits, et aucun ne sait que l'autre existe. Ouvrez l'un pendant que l'autre est ouvert et vous obtenez deux modales empilées, deux pièges de focus qui se battent, et deux gestionnaires Esc.

La correction tient en huit lignes, et elle vit dans le module de bus de la palette — comme ça, aucun composant n'a besoin d'importer l'autre :

let activeCloser = null;

export function setActiveOverlay(closeFn) {
  if (activeCloser && activeCloser !== closeFn) activeCloser();
  activeCloser = closeFn;
  return () => {
    if (activeCloser === closeFn) activeCloser = null;
  };
}

Chaque dialogue appelle setActiveOverlay(close) à son ouverture, et appelle la fonction de nettoyage qu'il récupère à sa fermeture. Celui qui s'ouvre en second ferme celui qui était ouvert en premier. Ajouter un troisième overlay plus tard ne demande de changer absolument rien.

Un indice autorisé à apparaître une seule fois (passez si vous ne voulez que la bulle)

La pastille de la palette et l'anneau pulsant de la bulle sont des indices de première visite, et tous deux suivent les trois mêmes règles :

• Le flag localStorage est écrit quand l'indice est affiché, pas quand il est fermé. Un visiteur qui l'ignore ne le revoit pas à la page suivante.
• Les délais sont décalés — la pastille de la palette à 4 ou 10 secondes, le pulse de la bulle à 15 — pour que les deux ne s'animent jamais ensemble et ne passent pas pour un pop-up.
• L'anneau pulsant est entièrement supprimé sous prefers-reduced-motion, pas seulement ralenti.

Le délai de la palette est volontairement différent selon le type de page, et la raison mérite d'être dite : 10 secondes sur un article, pour que la pastille n'interrompe jamais quelqu'un qui vient de commencer à lire. La page d'accueil n'a aucune lecture à interrompre et c'est là que les visiteurs rebondissent le plus vite, donc elle a 4 secondes — assez long pour ne pas ressembler à un pop-up au chargement.

function delayFor(pathname) {
  if (HOME_PATH.test(pathname)) return HOME_DELAY_MS;
  if (ARTICLE_PATH.test(pathname)) return ARTICLE_DELAY_MS;
  return null;
}

Renvoyer null — plutôt qu'un grand nombre — fait de « ce chemin n'affiche rien » un état distinct et lisible, au lieu d'un délai qu'il faut déchiffrer en plissant les yeux.

Conclusion

Les fonctionnalités de cette série ont pris des semaines. Les rendre trouvables a pris un après-midi, et il est tout à fait possible que cet après-midi ait compté davantage.

Il y a un mode d'échec propre à la construction de ses propres outils : vous êtes le seul utilisateur incapable d'évaluer la découvrabilité, parce que vous ne pouvez pas désapprendre où se trouvent les choses. De l'intérieur, chaque porte paraît évidente. Le seul remède que j'ai trouvé est mécanique : listez les points d'entrée d'une fonctionnalité, et pour chacun, notez ce que le lecteur doit déjà savoir pour l'utiliser. Tout ce dont la réponse est « que cette fonctionnalité existe » n'est pas un point d'entrée du tout.

Et en cas de doute, mettez un bouton dans le coin. Tout le monde sait ce qu'il fait.

Chaque serveur de mon environnement n'est accessible qu'à travers ma propre VM Windows qui joue le rôle de bastion. L'article sur ProxyJump et les DevContainers montre une config avec un seul alias. Ajoutez un deuxième serveur et la config double. Ajoutez-en dix et ça devient un problème de maintenance : changez une fois le hostname du bastion et vous réécrivez dix stanzas, chacune portant les mêmes lignes ProxyJump et IdentityFile.

La config ci-dessous couvre n'importe quel nombre de serveurs sans aucune répétition.

La configuration

Les deux chemins de connexion fonctionnent immédiatement — un alias court et un FQDN complet, sans aucun flag :

$ ssh project_prod "whoami && hostname"
user-b
server-prod
$ ssh server-test.cloud.project-a.internal "whoami && hostname"
user-a
server-test▋

Pas de flag ProxyJump, pas de clé explicite — la config gère les deux de façon transparente. Créez C:\Users\your_laptop_user\.ssh\config (Windows ; WSL inclus) ou ~/.ssh/config (Linux/macOS) avec ceci :

# 1. Bastion — no ProxyJump, no IdentityFile
Host windows-vm-ip
    User vm-user

# 2. Domain defaults — in effect when connecting via full FQDN only
Host *.cloud.project-a.internal
    User user-a

Host *.cloud.corp.example
    User user-b

Host *.office.corp.example
    User user-b

# 3. Short aliases — HostName + User
#    (domain defaults above do not apply to aliases — see article)
Host project_test
    HostName server-test.cloud.project-a.internal
    User user-a

Host project_prod
    HostName server-prod.office.corp.example
    User user-b

# 4. Explicit exceptions — bypass the bastion for specific hosts
#    Must come BEFORE "Host *" — SSH uses first-value-wins per directive
Host github.com
    ProxyJump none

# 5. Global defaults — fallback for every host except the bastion
Host * !windows-vm-ip
    ProxyJump vm-user@windows-vm-ip
    IdentityFile ~/.ssh/id_ed25519

Comment SSH lit un fichier de configuration

Trois règles expliquent pourquoi les stanzas se composent sans conflit :

• Plusieurs stanzas peuvent correspondre. Lancer ssh project_prod amène SSH à parcourir le fichier de haut en bas et à collecter les réglages de chaque stanza Host qui correspond à project_prod, pas seulement la première.
• La première valeur l'emporte pour chaque réglage — l'inverse de la plupart des outils. En CSS, dans les fichiers .env ou dans la plupart des systèmes de configuration, la dernière déclaration écrase les précédentes. SSH fait l'inverse : la première valeur rencontrée est conservée, et les stanzas suivantes ne peuvent que compléter les réglages non encore définis. Mettez la stanza la plus spécifique en premier ; le fallback wildcard en dernier.
• Les motifs correspondent à l'argument de la ligne de commande, pas au hostname résolu. Host *.office.corp.example correspond à ssh server-prod.office.corp.example. Il ne correspond pas à ssh project_prod, même si le HostName de project_prod se résout en server-prod.office.corp.example.

Les cinq sections

Le snippet de config ci-dessus est découpé en cinq sections numérotées — voici ce que fait chacune et pourquoi elle est placée dans cet ordre.

Section 1 — Définition du bastion. Déclare le jump host avec son nom d'utilisateur. Pas de ProxyJump ici (il boucherait sur lui-même) et pas d'IdentityFile (la VM utilise l'authentification que vous avez configurée séparément pour elle).

Section 2 — Valeurs par défaut par domaine. Elles s'appliquent quand vous tapez un FQDN complet comme ssh server-prod.office.corp.example. SSH récupère le User ici, puisqu'aucune stanza précédente ne l'a défini. Plusieurs stanzas de domaine avec le même nom d'utilisateur, c'est normal — une par suffixe de domaine. Ces stanzas sont aussi utiles pour les scripts qui construisent des hostnames par programme ou pour les appels ssh-copy-id.

Section 3 — Alias courts. Chaque alias déclare HostName (le vrai FQDN) et User. Ajouter un nouvel alias de serveur, c'est exactement deux lignes.

Section 4 — Exceptions explicites. Tout host qui ne doit pas passer par le bastion — un service d'hébergement Git, un runner CI, une API SaaS — reçoit ProxyJump none ici. La position est structurante : cette stanza doit venir avant Host *.

Section 5 — Valeurs globales par défaut. Le préfixe ! dans Host * !windows-vm-ip signifie « tous les hosts sauf le bastion ». Placée en dernier, cette stanza fournit ProxyJump et IdentityFile comme fallbacks pour chaque stanza précédente qui ne les a pas définis — c'est-à-dire toutes. N'importe quelle stanza des sections 2, 3 ou 4 peut écraser ces valeurs simplement en déclarant la directive en premier, sans toucher à la section 5.

Renforcer la section 5 (optionnel)

Quatre directives étendent les valeurs globales sans en changer la logique. Ajoutez celles qui correspondent à votre environnement — aucune n'est requise pour que la config fonctionne.

# 4. Explicit exceptions — bypass the bastion for specific hosts
#    Must come BEFORE "Host *" — SSH uses first-value-wins per directive
Host github.com
    ProxyJump none

# 5. Global defaults — fallback for every host except the bastion
Host * !windows-vm-ip
    ProxyJump vm-user@windows-vm-ip
    IdentityFile ~/.ssh/id_ed25519

    # Optional — prevent silently-dropped idle connections
    ServerAliveInterval 30
    ServerAliveCountMax 3

    # Optional — fail fast instead of waiting the default 2 minutes
    ConnectTimeout 5

• ServerAliveInterval 30 / ServerAliveCountMax 3 — SSH envoie un paquet keepalive toutes les 30 secondes. Après 3 paquets sans réponse (90 secondes de silence), la connexion est fermée proprement au lieu de rester bloquée sur un prompt gelé. Sans ça, un terminal inactif sur un serveur d'entreprise se fige souvent sans aucun message d'erreur.
• ConnectTimeout 5 — échoue après 5 secondes si le serveur est injoignable. Sur un réseau d'entreprise avec un bastion fiable, le timeout par défaut de 2 minutes n'est que du bruit.

    ControlMaster auto
    ControlPath ~/.ssh/cm_%C
    ControlPersist 10m

Pourquoi chaque alias a besoin de sa propre ligne User (à passer si la config fonctionne déjà chez vous)

Les stanzas de domaine de la section 2 ne définissent User que quand SSH y trouve une correspondance — et comme noté plus haut, SSH fait correspondre les motifs à l'argument de la ligne de commande, pas au hostname résolu.

En lançant ssh project_prod :

1. Ne correspond pas à Host *.office.corp.example (section 2) — project_prod n'est pas un FQDN.
2. Correspond à Host project_prod (section 3) → applique HostName server-prod.office.corp.example et User user-b.
3. Ne correspond pas à Host github.com (section 4) — project_prod n'est pas dans cette liste.
4. Correspond à Host * !windows-vm-ip (section 5) → applique ProxyJump et IdentityFile.

Sans la ligne User dans la stanza de l'alias, SSH retombe sur votre nom d'utilisateur Windows local pour cette connexion — ce qui est presque certainement faux.

En lançant directement ssh server-prod.office.corp.example :

1. Correspond à Host *.office.corp.example (section 2) → User user-b.
2. Ne correspond pas à Host github.com (section 4) — pas dans cette liste.
3. Correspond à Host * !windows-vm-ip (section 5) → ProxyJump, IdentityFile.

Les deux chemins arrivent sur le bon utilisateur. Ils ont juste besoin de stanzas différentes pour y arriver.

Une réserve : le wildcard est vraiment universel (à passer si cette machine est purement professionnelle)

Host * !windows-vm-ip s'applique à chaque connexion SSH depuis cette machine — y compris ssh github.com ou ssh localhost. Les connexions vers des hosts externes tenteront un ProxyJump à travers la VM et échoueront si la VM n'est pas joignable.

ssh: Could not resolve hostname your-bastion: Name or service not known

Trois options si ça vous pose problème :

• Remplacez Host * par une liste de domaines explicite : Host *.project-a.internal *.cloud.corp.example *.office.corp.example. Les connexions vers tout ce qui est en dehors de cette liste ignorent complètement le bastion.
• Gardez Host * si cette machine utilise SSH exclusivement pour des serveurs internes à votre réseau d'entreprise. Sur une machine de travail dédiée, le wildcard convient très bien.
• Écrasez des hosts spécifiques au-dessus de la section 4. Comme les valeurs globales sont en dernier, toute stanza placée avant elles l'emporte. Ajoutez une exemption n'importe où au-dessus de la section 4 — la position à l'intérieur des sections 1 à 3 n'a pas d'importance :

# Anywhere above section 4 — fits naturally in section 3 alongside the other aliases
Host github.com gitlab.com
    ProxyJump none
    IdentityFile ~/.ssh/id_ed25519_personal

# Section 4 — global defaults (last, unchanged)
Host * !windows-vm-ip
    ProxyJump ...

• Découpez la config avec Include — la solution la plus propre pour une machine utilisée à la fois pour du SSH professionnel et personnel :

# ~/.ssh/config
Include ~/.ssh/config.d/work
Include ~/.ssh/config.d/personal

~/.ssh/config.d/work contient la config d'entreprise complète (bastion, stanzas de domaine, alias, valeurs globales en dernier). ~/.ssh/config.d/personal contient une config propre sans routage par bastion. Les directives Include sont traitées de haut en bas avant tout bloc Host du fichier principal — OpenSSH 7.3+ requis.

Bonus : se connecter directement en tant qu'autre utilisateur

Certains serveurs exigent que vous vous connectiez avec votre propre compte puis basculiez vers un utilisateur applicatif — sudo su app_user suivi de cd /opt/project. La directive RemoteCommand automatise toute la séquence depuis l'alias.

Le générateur ci-dessous produit deux alias par serveur : un alias simple pour VSCode Remote Explorer (sans RemoteCommand) et une variante _app pour les sessions de terminal qui vous connecte directement en tant qu'utilisateur applicatif.

Générez votre configuration complète

Remplissez vos valeurs une fois et copiez le résultat directement dans ~/.ssh/config. Pour un second projet, copiez-collez uniquement les alias de la section 3 et changez le nom du projet — le bastion et les valeurs globales sont déjà en place.

# 1. Bastion — no ProxyJump, no IdentityFile
Host windows-vm-ip
    User vm-user

# 2. Domain defaults — in effect when connecting via full FQDN only
Host *.office.corp.example
    User user-b
# 3. Short aliases
Host project_test_app
    RequestTTY yes
    RemoteCommand sudo -u app-user bash -c "cd /opt/folder_devcontainer && exec bash -l"

Host project_test project_test_app
    HostName server-test.office.corp.example
    User user-b

Host project_prod_app
    RequestTTY yes
    RemoteCommand sudo -u app-user bash -c "cd /opt/project && exec bash -l"

Host project_prod project_prod_app
    HostName server-prod.office.corp.example
    User user-b

# 4. Global defaults — fallback for every host except the bastion
Host * !windows-vm-ip
    ProxyJump vm-user@windows-vm-ip
    IdentityFile ~/.ssh/id_ed25519

    # Optional — prevent silently-dropped idle connections
    ServerAliveInterval 30
    ServerAliveCountMax 3

$ ssh vm-user@windows-vm-ip "echo bastion-ok"
bastion-ok

Le RemoteCommand de la variante _app enchaîne deux choses : un cd vers le répertoire de l'application et un exec bash -l pour démarrer un shell de login en tant qu'utilisateur applicatif. RequestTTY yes alloue un pseudo-terminal — sans ça, la session se ferme immédiatement après la commande au lieu de vous donner un shell interactif.

$ ssh project_test_app
mass_upload@server-test:/opt/folder_devcontainer$

$ ssh project_prod_app
app-user@server-prod:/opt/project$

Les quatre alias récupèrent automatiquement le ProxyJump global de la section 4.

RemoteCommand sudo su - app-user -c "cd /opt/project && exec bash -l"

Avertissement pour les environnements de production

Une bannière RemoteCommand n'est visible que par celui qui a configuré cet alias SSH. Le bon endroit pour un avertissement de production, c'est le serveur lui-même — ainsi il atteint tous les utilisateurs, quel que soit leur client.

Déposez un script dans /etc/profile.d/ sur le serveur. Chaque shell interactif source ce répertoire à la connexion :

#!/usr/bin/env bash
case "$(hostname -s)" in
  *prod*|*prd*)
    printf '\033[38;5;88;48;5;224m  ⚠  Production server — be careful!  \033[0m\n\n'
    export PS1='\[\033[38;5;88;48;5;224m\] ⚠ PROD \[\033[0m\] \u@\h:\w\$ '
    ;;
esac

La paire de couleurs 38;5;88 (bordeaux foncé) sur 48;5;224 (rose pâle) est clairement visible sans être agressive — un rappel, pas un panneau d'alarme.

$ ssh project_prod_app
  ⚠  Production server — be careful!

app-user@server-prod:/opt/project$

Comme exec bash -l dans le RemoteCommand démarre un shell de login, les scripts de profil s'exécutent et la bannière apparaît aussi sur chaque connexion _app. Aucun changement nécessaire dans la config SSH.

if [[ -f /etc/env-type ]] && grep -qx "production" /etc/env-type; then

Conclusion

Une seule stanza wildcard élimine la répétition de ProxyJump et IdentityFile dans chaque alias. Les stanzas de domaine ajoutent les noms d'utilisateur pour l'accès direct par FQDN. Les alias courts répètent User explicitement — parce que SSH fait la correspondance sur ce que vous tapez, pas sur ce que l'alias résout.

Ajouter un nouveau serveur, c'est deux lignes : HostName et User. Le routage est déjà géré. Quand un serveur exige un utilisateur et un répertoire spécifiques, RemoteCommand transforme cette séquence en un simple alias. Et quand un serveur de production a besoin d'un avertissement visuel clair pour tout le monde, /etc/profile.d/ est le bon endroit — pas la config SSH.

Si vous devez générer ou gérer vos clés SSH, cet article couvre la génération de clés ed25519 et l'autorisation GitHub depuis zéro — la même clé que celle utilisée dans la ligne IdentityFile ci-dessus.

La recherche sur un blog personnel est presque toujours décevante, et j'ai mis un moment à comprendre pourquoi. Ce n'est pas la faute du moteur de recherche — le mien indexe parfaitement chaque mot de chaque page. Le problème, c'est qu'il ne peut trouver que les mots que j'ai écrits.

J'écris « réduire la taille finale de l'image avec des builds multi-stage ». Le lecteur en galère tape « mon image docker est énorme ». Zéro résultat. L'article dont il avait besoin est là, indexé, comparé à un vocabulaire qu'il n'a jamais employé.

La réponse habituelle, ce sont les embeddings : tout transformer en vecteurs, comparer des sens plutôt que des mots. Mais ça veut dire un modèle dans le navigateur, ou un appel d'API à chaque frappe, pour un blog statique sans backend. Il existe une façon bien moins coûteuse de faire le pont entre deux vocabulaires — et ça commence par remarquer que ce pont ne doit être construit qu'une seule fois.

Ce que vous obtenez

La page /faq s'ouvre sur un hub : des cartes de sujets, une par tag principal — Docker, AI, Bash, WSL, et d'autres. Chaque carte indique combien de questions y sont classées. Cliquez sur l'une d'elles et vous arrivez sur une page qui liste toutes les questions de ce sujet, chacune pointant vers le titre d'article exact qui y répond :

Le même index alimente aussi une boîte de recherche sur cette page. Tapez un problème avec vos propres mots — « mon image docker est trop grosse », « comment installer joomla » — et vous obtenez des questions, pas des titres de page. Chaque résultat pointe vers le titre exact qui y répond :

C'est toute l'idée, et le reste de cet article explique comment c'est construit.

Pourquoi ça marche sans modèle dans le navigateur

L'idée est minuscule et c'est tout l'article : le travail sémantique n'a pas à se faire au moment de la recherche.

• La requête d'un lecteur et la prose d'un article sont écrites dans deux vocabulaires différents. Quelque chose doit traduire entre les deux.
• Cette traduction est une propriété fixe de l'article. Elle ne dépend ni de qui cherche, ni de quand. Elle peut donc être calculée une fois et stockée.
• Une fois qu'un modèle a déjà formulé « comment empêcher mon image Docker d'être énorme ? » et l'a classée à côté du bon titre, comparer la requête d'un lecteur à cette phrase devient un simple problème de similarité de chaînes. Un classement lexical vieux de vingt ans s'en sort parfaitement.
• Ce qui part vers le navigateur, c'est donc une liste de phrases et une fonction de scoring — pas un modèle, pas un index vectoriel, pas un appel réseau.

Le build devient plus lent (environ 11 secondes par article, une seule fois). Chaque lecteur ensuite obtient une réponse instantanée.

Générer les questions

Le générateur demande à une instance Ollama locale des questions sur un article, et les écrit dans un fichier sidecar à côté de celui-ci — la même convention que celle déjà utilisée par mes tooltips ELI5 pour leur propre contenu généré :

$ time yarn questions blog/2025/09/12/docusaurus-go-top/index.md --force

✅ Written: blog/2025/09/12/docusaurus-go-top/index.md.questions.json
   8 questions.

real    0m11.147s

$ yarn questions:bulk --dry-run --limit 4

🔍 4 article(s) under blog (--limit 4).
  [SKIP] blog/2023/11/02/docker-php-run-script-or-website/index.md
  [SKIP] blog/2023/11/02/keepass-start-rdp/index.md
  [SKIP] blog/2023/11/02/welcome/index.md
  [SKIP] blog/2023/11/02/wslg-rpd-connection/index.md

Dry run — nothing written.

Le résultat est un petit fichier JSON, index.md.questions.json, committé à côté de l'article :

Trois choses rendent cette sortie utilisable plutôt que simplement plausible.

On explique au modèle ce que « spécifique » veut dire. Le system prompt interdit purement et simplement les questions génériques (« Qu'est-ce que Docker ? »), exige un mélange de requêtes courtes façon mots-clés et de phrases complètes, et interdit deux questions qui ne diffèrent que par l'ordre des mots :

- Every question must be SPECIFIC to this article's actual content — never generic
  ("What is Docker?", "How does Markdown work?").
- Vary the phrasing style: some short keyword-style queries, some full questions.
- Each question maps to exactly one heading by index. Index 0 means "the article as a
  whole / introduction", not tied to a specific heading.
- Do not invent facts not supported by the material given.

La forme de la réponse est imposée, pas espérée. Ollama accepte un schéma JSON dans format:, donc le modèle ne peut pas renvoyer de la prose, une liste Markdown ou un champ nommé différemment. Le script valide quand même chaque élément après coup, et fait échouer l'article entier s'il en reste moins de cinq — une entrée maigre est pire qu'aucune entrée.

Les titres sont résolus en vraies ancres. Le prompt donne au modèle une liste numérotée de titres et lui demande un index ; le script remappe cet index vers le slug que Docusaurus va lui-même générer, avec le même package github-slugger que Docusaurus utilise en interne. Un mauvais index n'est pas fatal — la question retombe en haut de l'article au lieu d'être jetée.

Voici le générateur complet :

Servir 2 160 questions de trois manières différentes

Un plugin Docusaurus agrège les 259 sidecars en un seul index. Le point intéressant, c'est qu'il n'expédie pas cet index une fois — il l'expédie trois fois, sous trois formes différentes, parce qu'il a trois consommateurs aux besoins incompatibles :

C'est la troisième ligne qui compte. Le corpus complet pèse 468 Ko (63 Ko gzippés), et la boîte de recherche vit dans un composant monté sur chaque page du site. L'exposer via setGlobalData aurait embarqué les 468 Ko dans le JavaScript de chaque page, que quelqu'un tape un caractère ou non.

Le plugin l'écrit donc directement sur disque comme asset statique, et le client le fetch la première fois que quelqu'un ouvre vraiment la boîte de recherche :

Le fetch est mis en cache au niveau du module, donc la palette et la page /faq partagent un seul téléchargement — et un fetch raté vide le cache au lieu de l'empoisonner, pour qu'un lecteur ayant cherché avant la fin du build du serveur de dev puisse simplement réessayer :

Et la boîte de recherche elle-même :

Sous le capot (passez votre chemin si vous voulez juste les questions)

Interroger l'index depuis la ligne de commande

Le fichier JSON est un simple tableau, vous pouvez donc le sonder hors du navigateur en quelques lignes. Pratique pour déboguer l'index avant de le livrer, ou pour vérifier si une formulation précise correspond :

$ npx tsx --eval "
import { buildSearchIndex, search } from './src/components/AskMyBlog/utils.ts';
import fs from 'fs';
const rel = 'questions-index-plugin/static/questions-index.json';
const p = ['.docusaurus', '.docusaurus-dev'].map(d => d + '/' + rel).find(fs.existsSync);
if (p === undefined) throw new Error('Run yarn build or start the dev server first');
const corpus = JSON.parse(fs.readFileSync(p, 'utf8'));
const index = buildSearchIndex(corpus);
for (const r of search(index, process.argv[1], 4)) {
  console.log(r.question);
  console.log('    ' + r.title + '  ->  ' + r.permalink + (r.anchor ? '#' + r.anchor : ''));
}" "run docusaurus in docker"

How do I run my Docusaurus site using Docker?
    Running Docusaurus with Docker  ->  /blog/docusaurus-docker#run-docusaurus
What commands are used to build and run the production Docker image for Docusaurus?
    Running Docusaurus using Docker  ->  /blog/running-docusaurus-with-docker#build-and-run-the-production-image
How do I run Quarto Markdown in Docker?
    Running Quarto Markdown in Docker  ->  /blog/docker-quarto
How do I run Firefox in a Docker container?
    Docker - Run Graphical User Interfaces - Firefox, Chrome & GIMP  ->  /blog/docker-run-linux-gui#creating-our-own-chrome-docker-image

BM25 en quarante lignes

Le classement, c'est Okapi BM25 — fréquence des termes avec saturation, plus normalisation par la longueur, pondérée par la fréquence inverse de document. C'est ce qu'utilisent Lucene et Elasticsearch, et ça tient dans un petit fichier parce que chaque « document » ici est une seule question d'une douzaine de mots.

Deux adaptations étaient nécessaires pour cette longueur de document inhabituellement courte.

Le matching par préfixe, développé une fois par requête. Un lecteur qui tape docus n'a pas fini son mot, donc un token inconnu de trois caractères ou plus est développé vers tous les termes indexés qu'il préfixe. En dessous de trois caractères, un préfixe correspond à trop de vocabulaire pour signifier quoi que ce soit, donc les tokens inconnus courts sont simplement écartés. Point crucial : l'expansion a lieu une fois par requête, pas une fois par document — la boucle de scoring ne voit jamais que de vrais termes indexés.

Un tokenizer qui découpe les mots composés sans les perdre. CaesiumCLT tokenisé naïvement est un seul token indivisible, donc un lecteur qui tape « caesium » ne trouve rien. Insérer une frontière avant de passer en minuscules règle ça — mais alors WordPress devient word + press, et quelqu'un qui tape « wordpress » en un mot ne correspond à aucune des deux moitiés. La solution est une union plutôt qu'un remplacement : garder à la fois la forme découpée et la forme entière.

export function tokenize(text: string): string[] {
  const withBoundaries = text.replace(/([a-z0-9])([A-Z])/g, "$1 $2");
  const split = withBoundaries.toLowerCase().match(/[a-z0-9]+/g) || [];
  const whole = text.toLowerCase().match(/[a-z0-9]+/g) || [];
  return [...new Set([...split, ...whole])];
}

Le problème des doublons

Si quarante articles génèrent chacun « Comment installer Docker ? », l'index ne sert à rien — le lecteur obtient quarante lignes identiques et aucun signal. Le plugin normalise chaque question et supprime toutes les instances en collision, y compris la première. Ce dernier détail est volontaire : une question qui n'est pas spécifique à exactement un article a déjà enfreint la règle du prompt, donc en garder une copie reviendrait quand même à livrer une mauvaise entrée. Sur mon corpus, ça retire 5 questions sur 2 055. Le prompt fait l'essentiel du travail ; ceci n'est que le filet de sécurité.

Les sidecars sont faits pour être édités à la main

La génération est un premier jet. La plupart des entrées sont correctes, certaines sont une blague reprise telle quelle dans la prose d'un article et reformatée en question. Un petit élagueur interactif les retrouve par mot-clé et permet de supprimer par numéro :

$ yarn questions:edit "dinosaur"

blog/2024/05/17/some-article/index.md.questions.json
  [0] How do I install the CLI? → #installation
  [1] How can I play with a green dinosaur?
  [2] What does the --force flag do? → #options
Delete which number(s)? (space-separated, Enter to skip): 1
  ✅ Removed 1 question(s), 11 left.

Supprimer une question ne touche jamais à l'article lui-même, ce qui compte pour la dernière pièce.

Détecter la dérive

Une question générée peut pourrir en silence : renommez un titre et son ancre casse ; réécrivez une section et les questions cessent de la décrire. yarn questions:check compare le sourceHash stocké dans chaque sidecar au contenu actuel de l'article et signale STALE, plus les articles qui n'ont aucun sidecar. Par défaut il se contente de rapporter ; --strict échoue sur les entrées périmées mais jamais sur la couverture manquante, parce qu'un article fraîchement écrit n'a légitimement aucune question tant que vous n'avez pas lancé le générateur dessus.

Les pages de sujet embarquent des données structurées FAQ

Chaque page /faq/<topic> émet du JSON-LD FAQPage. Autant être honnête sur le retour : Google a restreint les rich results FAQ en août 2023 à un ensemble étroit de sites gouvernementaux et de santé faisant autorité, donc un blog personnel n'obtiendra pas l'affichage dépliable. Ça reste du balisage correct et conforme aux standards, que d'autres consommateurs lisent — mais pas un gain garanti dans la page de résultats.

Conclusion

J'ai commencé en voulant de la recherche sémantique et j'ai fini sans avoir besoin de la moindre sémantique à l'exécution. Le modèle a fait le plus dur une fois, hors ligne, sur ma propre machine, gratuitement — et ce qu'il a laissé derrière lui, ce sont 2 160 phrases en anglais courant qu'un classement lexical ordinaire traite à merveille.

Ce recadrage vaut la peine d'être transposé ailleurs. « Ça nécessite un modèle » signifie très souvent « ça a nécessité un modèle, une fois, et maintenant ça nécessite un fichier ». La version de votre fonctionnalité qui fait tourner un modèle de langage dans le navigateur de chaque visiteur et celle qui livre un fichier JSON calculé au build peuvent produire la même réponse — et une seule des deux fonctionne encore quand la clé d'API expire.

Mon index complet, généré localement et committé dans Git, pèse 63 Ko sur le réseau. C'est moins que l'image de bannière en haut de cet article.

Mince. Je viens de lancer docker images et voilà ce que j'ai vu : myapp:latest — 1.19 GB. Une application web Python avec cinq dépendances, et elle a gonflé au-delà du gigaoctet. Quelque chose cloche sérieusement dans ce Dockerfile.

Le problème avec l'obésité des images Docker, c'est qu'elle est invisible tant qu'on ne la cherche pas. Vos containers démarrent, votre app tourne, tout semble normal — et pendant ce temps vous expédiez 400 Mo de cache apt et d'outils de build en production à chaque déploiement.

C'est là qu'intervient dive. C'est un inspecteur d'images en mode terminal qui permet de naviguer dans les layers de n'importe quelle image Docker, de voir exactement ce que chaque instruction RUN, COPY et ADD a ajouté ou supprimé, et d'obtenir un score d'efficacité sans pitié en bas de l'écran. Voyez ça comme une machine à rayons X pour vos images.

Qu'est-ce que Dive ?

Au fond, une image Docker est une pile de layers en lecture seule. Chaque instruction de votre Dockerfile qui touche au système de fichiers crée un nouveau layer. apt-get install — nouveau layer. pip install — nouveau layer. COPY — nouveau layer.

Voilà le piège : si vous installez un package dans le layer 3, puis supprimez son cache dans le layer 5, les données du cache sont toujours dans l'image. La suppression marque seulement les fichiers comme « opaques » dans le layer supérieur — les octets du layer 3 sont toujours là, téléchargés à chaque docker pull.

dive rend tout cela visible. Panneau de gauche : l'arborescence de fichiers du layer sélectionné. Panneau de droite : la liste des layers avec leurs tailles. En bas : votre score d'efficacité et l'espace total gaspillé.

Lancer Dive — aucune installation nécessaire

Vous me connaissez bien maintenant : j'aime mettre les choses dans des containers. Et dive dispose d'une image Docker officielle, donc aucune raison d'installer quoi que ce soit sur votre host :