DEV Community: yohann streibel

Guide pratique : Implémenter votre Wiki LLM avec Logseq et Claude Code

yohann streibel — Thu, 30 Apr 2026 12:29:12 +0000

Prérequis : Ce guide suppose que vous avez lu Le concept du Wiki LLM qui explique l'architecture et le fonctionnement du système.

Dans cet article pratique, nous allons :

Installer et configurer Logseq + Claude Code
Créer les 9 skills nécessaires
Initialiser le wiki et ingérer vos notes existantes
Découvrir les workflows quotidiens
Explorer les outils optionnels avancés

⚠️ Confidentialité et données sensibles

Avant de commencer : tout fichier lu par Claude Code dans votre vault transite par l'API Anthropic (ou votre fournisseur LLM). Pages, journaux, assets — si Claude les lit pour ingérer, ils quittent votre machine.

Implications pratiques :

Évitez d'ingérer des fichiers contenant des secrets, mots de passe, tokens API
Sur un vault professionnel : vérifiez les politiques de votre organisation avant usage
Données personnelles sensibles (santé, finances, relations) : réfléchissez avant d'ingérer

Solution : .claudeignore

Créez un fichier .claudeignore à la racine de votre vault pour exclure des dossiers ou fichiers :

# .claudeignore
pages/secrets/
pages/finance/
journals/2020-*/     # Vieilles entrées à ne pas toucher
assets/*.pdf         # PDFs confidentiels

Claude Code respecte ce fichier et ne lira pas les chemins listés.

Installation et configuration

Étape 1 : Installer Logseq

# macOS
brew install --cask logseq

# Ou téléchargez depuis https://logseq.com/

Lancez Logseq et créez un nouveau graphe, par exemple ~/Logseq.

Étape 2 : Structure initiale

Logseq crée automatiquement pages/, journals/, et logseq/. Vous n'avez besoin de créer que :

cd ~/Logseq
mkdir -p .claude/skills

La structure finale sera :

~/Logseq/
├── pages/                    # Pages Logseq (vous écrivez ici)
├── journals/                 # Journal quotidien (vous écrivez ici)  
├── logseq/                   # Configuration Logseq
├── assets/                   # Images, PDFs (Logseq les place ici)
├── wiki/                     # Wiki géré par Claude (créé par setup)
│   ├── [thème]/             # Un dossier par thème détecté
│   │   ├── _index.md        # Index du thème
│   │   └── [pages].md       # Pages du thème
│   ├── _master-index.md     # Index global
│   ├── _log.md              # Journal des opérations
│   ├── _manifest.json       # État et tracking
│   └── _archive/            # Archives des rebuilds
└── .claude/
    └── skills/               # Les 9 skills
        ├── llm-wiki/
        ├── wiki-setup/
        ├── wiki-ingest/
        ├── wiki-update/
        ├── wiki-query/
        ├── wiki-status/
        ├── wiki-lint/
        ├── wiki-rebuild/
        └── cross-linker/

Étape 3 : Configuration Logseq

La plupart des paramètres sont corrects par défaut. Deux choses à vérifier :

Format Markdown : À la création du graphe, Logseq vous demande le format préféré. Choisissez Markdown (plutôt qu'Org-mode). Si votre graphe existant utilise déjà Markdown, vous n'avez rien à faire.

Dossier des assets : Dans Settings → Editor, vérifiez que Preferred file location for media files est sur In a dedicated assets folder. C'est la valeur par défaut.

Pour les paramètres avancés (ex : changer le nom du dossier assets), éditez directement logseq/config.edn dans votre vault :

;; logseq/config.edn
{
 :preferred-format :markdown
 :asset-directory "assets"
}

Les block-properties (title: ":, summary::) et les backlinks [[]] sont natifs à Logseq — pas besoin de les activer."

Étape 4 : Installer les plugins Logseq

Depuis Logseq, Plugins → Marketplace, installez :

Logseq Markmap : Visualisation de mindmaps
Logseq Mermaid : Diagrammes
Query Table : Tableaux depuis queries
Logseq Git : Versioning automatique (optionnel mais recommandé)

Étape 5 : Créer les skills Claude Code

Les skills sont des fichiers SKILL.md que Claude Code lit automatiquement pour adapter son comportement. Pour ce système wiki, vous devez créer 9 skills (voir tableau récapitulatif dans l'article 1).

Inspiration : Le projet obsidian-wiki propose une implémentation similaire pour Obsidian. Nous allons adapter ce concept pour Logseq.

Méthode recommandée : Laisser Claude Code générer les skills

cd ~/Logseq

Puis dans Claude Code, demandez :

Claude, je veux mettre en place un système de wiki LLM avec Logseq.
Crée les 9 skills suivants dans .claude/skills/ :

1. llm-wiki (fondation)
2. wiki-setup (initialisation)
3. wiki-ingest (ingestion complète)
4. wiki-update (mise à jour incrémentale)
5. wiki-query (interrogation)
6. wiki-status (dashboard)
7. wiki-lint (vérification)
8. wiki-rebuild (reconstruction)
9. cross-linker (tissage de liens)

Chaque skill doit :
- Définir la syntaxe Logseq native (title: ":, [[liens]], ((block-refs)))"
- Utiliser les primitives optimisées (Grep avant Read)
- Gérer le manifest (_manifest.json) et le log (_log.md)
- Travailler avec la structure pages/, journals/, wiki/

Inspire-toi du projet https://github.com/Ar9av/obsidian-wiki mais adapte 
pour Logseq (propriétés différentes, outliner-first, block-refs).

Claude générera les 9 fichiers SKILL.md dans leurs dossiers respectifs.

Vérification :

ls -la .claude/skills/
# Devrait afficher les dossiers : llm-wiki, wiki-setup, wiki-ingest, wiki-update,
# wiki-query, wiki-status, wiki-lint, wiki-rebuild, cross-linker

Étape 6 : Initialiser le wiki

Maintenant que les skills sont en place :

Claude, initialise mon wiki Logseq

Claude invoquera wiki-setup et :

Lira vos pages dans pages/*.md
Détectera les thèmes (sections ##)
Créera wiki/_master-index.md, wiki/_log.md, wiki/_manifest.json
Créera wiki/[thème]/_index.md pour chaque thème

Confirmation attendue :

✅ Wiki initialisé !

📁 5 thèmes détectés :
  - subrik (Kubernetes, infra)
  - capsule (projet capsule)
  - packmind (plateforme knowledge)  
  - e-tuch (organisation)
  - perso (notes personnelles)

📊 Prêt pour ingestion :
  - 52 pages
  - 120 journaux
  - 23 assets

💡 Prochaine étape : "ingère mon vault"

Étape 7 : Initialiser Git (optionnel mais recommandé)

cd ~/Logseq
git init
git add .
git commit -m "Initial commit: Logseq avec wiki initialisé"

Le wiki est un dépôt Git = historique complet des évolutions, possibilité de revenir en arrière, collaboration facilitée.

Template .gitignore recommandé :

# .gitignore — Logseq Wiki
logseq/bak/
logseq/.recycle/
.DS_Store
*.DS_Store
**/.DS_Store

# Fichiers temporaires
*.tmp
*.lock

Bonne pratique : committez avant chaque opération majeure (ingest, rebuild). Si une opération se passe mal, git checkout . vous ramène à l'état précédent en quelques secondes. Un alias utile : alias wiki-save='git add . && git commit -m "snapshot: $(date +%Y-%m-%d)"'.

Workflows quotidiens

Workflow 1 : Première ingestion complète

Vous venez d'initialiser le wiki. Vos notes Logseq contiennent déjà plein d'info. Lancez :

Claude, ingère mon vault

Claude invoque wiki-ingest et :

Inventorie vos sources : 52 pages, 120 journaux, 23 assets
Calcule les hashes pour chaque fichier
Distille source par source :
- Lit pages/kubernetes.md → détecte le thème "subrik"
- Extrait concepts : pods, services, ingress, helm
- Crée wiki/subrik/kubernetes-3488.md avec résumé structuré
- Crée wiki/subrik/helm.md pour l'outil
- Met à jour wiki/subrik/_index.md
Trace : Ajoute chaque source au manifest avec hash et timestamp
Log : Ajoute une entrée dans _log.md

Durée : ~5-10 minutes pour 100 sources (estimation, varie selon longueur des sources et modèle utilisé).

Confirmation attendue :

✅ Ingestion terminée !

📊 Résultats :
  - 52 pages ingérées
  - 120 journaux ingérés
  - 23 assets traités

📝 Wiki généré :
  - 5 thèmes : subrik, capsule, packmind, e-tuch, perso
  - 134 pages créées
  - 487 liens bidirectionnels

⏱️ Durée : 8min 23s

💡 Prochaines étapes :
  - "statut de mon wiki" pour voir le dashboard
  - "tisse les liens" pour enrichir les connexions
  - "vérifie mon wiki" pour un audit

Vérifier dans Logseq :

Ouvrez Logseq
Allez dans Graph View
Vous devriez voir wiki/ avec tous les thèmes et pages interconnectés

Workflow 2 : Update incrémental quotidien

Vous continuez à travailler dans Logseq. Vous :

Prenez des notes dans les journals
Enrichissez vos pages
Créez de nouvelles pages

Chaque jour ou semaine :

Claude, mets à jour mon wiki

Claude invoque wiki-update et :

Scanne toutes les sources
Compare hash : détecte 5 sources modifiées, 2 nouvelles
Traite uniquement les changements (mode merge intelligent)
Met à jour le manifest
Log l'opération

Résultat :

✅ Wiki mis à jour !

📝 Sources traitées :
  - 5 modifiées : pages/kubernetes.md, journals/2026_04_10.md, ...
  - 2 nouvelles : pages/terraform.md, pages/observability.md

📊 Impact wiki :
  - 7 pages mises à jour
  - 3 nouvelles pages créées
  - 18 nouveaux liens

⏱️ Durée : 2min 12s

Mode merge : Claude lit la page wiki existante, intègre les nouvelles infos sans écraser. Si contradiction détectée, il la signale mais ne choisit pas automatiquement.

Principe d'architecture : scripts pour le déterministe, LLM pour le sémantique

Un LLM peut se tromper — ou dans le cas d'agents enchaînés, inventer silencieusement un résultat qui paraît plausible. Pour les opérations déterministes (calcul de hash, comptage de fichiers, comparaison de chemins), déléguez à des scripts shell plutôt qu'à l'inférence :
# Calculer le hash d'une source — ne jamais laisser le LLM "estimer"
shasum -a 256 pages/kubernetes.md | awk '{print $1}'

# Compter les liens bidirectionnels dans wiki/
grep -r "\[\[wiki/" wiki/ | wc -l

# Détecter les pages orphelines (aucune référence entrante)
for page in wiki/**/*.md; do
  name=$(basename "$page" .md)
  count=$(grep -r "\[\[$name\]\]" wiki/ | wc -l)
  [[ $count -eq 0 ]] && echo "ORPHAN: $page"
done
Le skill invoque le script → le script retourne un fait — Claude interprète le résultat. Cette séparation rend le système fiable même avec des modèles moins "alignés" ou dans des workflows d'agents multiples.

Workflow 3 : Poser une question

Claude, comment gérer les secrets Kubernetes avec HashiCorp Vault ?

Claude invoque wiki-query et suit le protocole de retrieval optimisé :

Grep sur wiki/ : trouve wiki/subrik/kubernetes-secrets.md et wiki/subrik/vault.md
Lit ces 2 pages (pas toute la base)
Suit les liens : lit wiki/subrik/sealed-secrets.md mentionné
Synthétise avec citations Logseq

Réponse :

Pour gérer les secrets K8s avec Vault, deux approches :

## 1. Vault Agent Injector

[[wiki/subrik/vault]] peut injecter des secrets dans les pods via le
sidecar pattern. Configuration dans [[wiki/subrik/kubernetes-3488]].

Avantages :
- Rotation automatique
- Audit centralisé

## 2. External Secrets Operator

Alternative mentionnée dans [[wiki/subrik/kubernetes-secrets]] :
l'opérateur sync automatiquement Vault → K8s Secrets.

Plus d'info dans [[wiki/subrik/sealed-secrets]] pour la comparaison
des approches.

Mode rapide : Si vous dites "réponse rapide", Claude lit uniquement les summary:: sans lire le corps complet → réponse en 10s au lieu de 30s.

Workflow 4 : Audit de santé (Lint)

Après avoir ingéré ~20-30 sources, ou régulièrement pour garder le wiki sain :

Claude, vérifie mon wiki

Claude invoque wiki-lint et effectue 5 checks :

🔗 Liens cassés : [[wiki/subrik/page-inexistante]]
👻 Pages orphelines : Pages sans liens entrants
🗑️ Sources supprimées : Fichier dans manifest mais absent du vault
📋 Propriétés manquantes : Pages sans title:: ou summary::
⏰ NOW sans page : Tâches NOW dans journaux sans page wiki correspondante

Rapport :

🔍 Rapport Lint — Wiki Logseq
==============================

✅ Liens cassés : 0

👻 Pages orphelines : 2
  - wiki/subrik/draft-architecture.md (créée mais jamais liée)
  - wiki/e-tuch/old-process.md

🗑️ Sources supprimées : 1
  - pages/ancien-projet.md (supprimé le 2026-03-15, garde la page wiki)

📋 Propriétés manquantes : 3
  - wiki/capsule/api.md manque summary::
  - wiki/perso/idees.md manque sources::
  - wiki/subrik/wip.md manque updated::

⏰ Tâches NOW sans page : 2
  - "Implémenter API Gateway" (journal 2026-04-09) → suggère création wiki/capsule/api-gateway
  - "Migrer base Postgres" (journal 2026-04-08) → suggère mise à jour wiki/subrik/postgres

💡 Suggestions :
  1. Crée des liens vers les 2 pages orphelines
  2. Ajoute les propriétés manquantes
  3. Lance "update" pour intégrer les 2 tâches NOW relevées

Workflow 5 : Tissage de liens

Après une grosse ingestion, enrichissez le graphe :

Claude, tisse les liens dans mon wiki

Claude invoque cross-linker et :

Construit le registre : map de tous les titres → chemins
Scanne chaque page : détecte mentions de titres sans [[lien]]
Ajoute liens : première occurrence seulement
Vérifie bidirectionnalité : si A → B, vérifie que B → A

Résultat :

🔗 Cross-Linker — Résultat
==========================

Pages analysées   : 134
Liens ajoutés     : 87
Liens bidirectionnels vérifiés : 87

Pages les plus liées (hubs) :
  1. [[wiki/subrik/kubernetes-3488]] — 23 liens entrants
  2. [[wiki/capsule/architecture]] — 18 liens entrants
  3. [[wiki/e-tuch/processes]] — 15 liens entrants

Densité de liens : 3.2 (moyenne 3.2 liens par page)

💡 Ton graphe de connaissance est maintenant beaucoup plus connecté !

Workflow 6 : Dashboard de statut

À tout moment, voyez l'état du wiki :

Claude, statut de mon wiki

Claude invoque wiki-status :

📊 Statut du Wiki Logseq
========================

📁 Sources
  Pages     : 55 total, 52 ingérées, 3 non ingérées
  Journaux  : 125 total, 120 ingérés, 5 non ingérés

📝 Wiki
  Pages créées     : 134 (dans 5 thèmes)
  Densité de liens : 3.2
  Dernière mise à jour : 2026-04-10 16:45

🔄 Delta
  Sources modifiées depuis dernier update : 8
  Nouvelles sources depuis dernier ingest : 3

  Nouveaux journaux :
    - journals/2026_04_11.md
    - journals/2026_04_12.md
    - journals/2026_04_13.md

⚠️ Alertes
  Pages orphelines : 2
  Tâches NOW non trackées : 2

💡 Suggestion : Lance "update" pour ingérer 8 changements + 3 nouvelles sources

Workflow 7 : Rebuild complet

Si le wiki a divergé ou vous voulez repartir de zéro en gardant l'archive :

Claude, rebuild mon wiki

⚠️ Claude demande confirmation :

⚠️  ATTENTION : Opération destructive

Contenu actuel :
  - 134 pages
  - 5 thèmes
  - Dernière màj : 2026-04-10

Archive destination : wiki/_archive/2026-04-13/

Veux-tu continuer ? (oui/non)

Si oui :

Archive tout wiki/ vers wiki/_archive/2026-04-13/
Réinitialise manifest + log
Propose "initialise + ingère pour reconstruire"

Exemple concret : Premier jour avec un vault existant

Vous avez déjà 2 ans de notes Logseq. Voyons le cycle complet.

1. Installation (30 min)

# Installer Logseq
brew install --cask logseq

# Dans votre vault existant
cd ~/mon-vault-logseq
mkdir -p .claude/skills

# Les skills sont déjà créés (étape 5)

2. Initialisation (2 min)

Claude, initialise mon wiki Logseq

✅ Wiki initialisé !

📁 8 thèmes détectés :
  work, projects, learning, health, finance, hobbies, people, ideas

📊 Prêt pour ingestion :
  - 342 pages
  - 730 journaux (2 ans)
  - 127 assets

3. Première ingestion (30-45 min pour ~1000 sources)

Claude, ingère mon vault

Claude distille vos 2 ans de notes. Vous pouvez continuer à travailler pendant ce temps.

✅ Ingestion terminée !

📊 Résultats :
  - 342 pages ingérées
  - 730 journaux ingérés
  - 127 assets traités

📝 Wiki généré :
  - 8 thèmes
  - 687 pages créées
  - 2,341 liens bidirectionnels

⏱️ Durée : ~37 minutes (estimation pour un vault de cette taille)

4. Enrichissement (5 min)

Claude, tisse les liens

🔗 Cross-Linker terminé !

- 423 liens additionnels ajoutés
- Densité : 4.8 liens/page

5. Audit (2 min)

Claude, vérifie mon wiki

🔍 Lint — quelques pages orphelines détectées, propriétés à compléter

6. Utilisation quotidienne

Chaque jour :

Vous travaillez normalement dans Logseq (pages, journals)
Une fois par jour ou semaine : Claude, update mon wiki
Posez des questions : Claude répond en s'appuyant sur le wiki

Chaque semaine :

Claude, statut pour voir l'évolution
Claude, vérifie mon wiki pour audit

Chaque mois :

Claude, tisse les liens pour enrichir les connexions

Le Layer "Lint + Heal" : Maintenance automatique

Lint (déjà vu)

wiki-lint détecte :

🔗 Liens cassés
👻 Pages orphelines
🗑️ Sources supprimées
📋 Propriétés manquantes
⏰ NOW sans pages

Heal (workflow manuel actuellement)

Le "Heal" consiste à corriger automatiquement certains problèmes :

Heal guidé (aujourd'hui)

Après un lint, vous dites :

Claude, fixe les problèmes détectés

Claude propose des fixes un par un, vous validez.

Recherche web pour données manquantes

Si une page wiki mentionne "Voir documentation officielle" sans lien :

Claude, complète [[wiki/subrik/terraform]] avec la doc officielle

Claude :

Cherche sur web "Terraform documentation"
Lit la doc
Enrichit la page wiki avec résumé + lien
Met à jour manifest

Use case : Remplir les trous de connaissance sans quitter le workflow.

CLI Tools optionnels

À petite échelle (~100 sources, ~400-500 pages), le système fonctionne parfaitement avec juste les skills et la recherche par Grep. Mais au-delà, vous pouvez ajouter des outils pour améliorer les performances.

1. qmd : Moteur de recherche hybride local

qmd est un moteur de recherche pour markdown avec :

BM25 (keyword search)
Vector search (embeddings)
LLM re-ranking
Tout en local, pas de cloud

Installation :

brew install qmd

Usage :

# Indexer votre wiki
cd ~/Logseq
qmd index wiki/

# Chercher
qmd search "kubernetes secrets management"

Intégration avec Claude : Créez un skill search-qmd dans .claude/skills/ qui appelle qmd via CLI. Claude peut alors l'invoquer pour des recherches sémantiques quand Grep ne suffit pas.

2. Web UI pour exploration directe

Créez une interface web simple pour naviguer le wiki sans passer par Claude :

# Serveur markdown simple
cd ~/Logseq/wiki
python3 -m http.server 8000

Ouvrez http://localhost:8000 → naviguez les fichiers markdown directement.

Ou mieux : Utilisez Markserv pour un rendu markdown en live :

npm install -g markserv
cd ~/Logseq/wiki
markserv

3. MCP Server pour qmd

Si vous utilisez qmd, créez un MCP server pour l'exposer à Claude :

// mcp-qmd-server.js
const { MCPServer } = require('@modelcontextprotocol/sdk');
const { exec } = require('child_process');

const server = new MCPServer({
  name: 'qmd-search',
  version: '1.0.0'
});

server.addTool({
  name: 'search_wiki',
  description: 'Semantic search in Logseq wiki using qmd',
  parameters: {
    query: { type: 'string', description: 'Search query' },
    limit: { type: 'number', default: 5 }
  },
  handler: async ({ query, limit }) => {
    return new Promise((resolve) => {
      exec(`qmd search "${query}" --limit ${limit}`, (error, stdout) => {
        resolve({ results: stdout });
      });
    });
  }
});

server.start();

Claude peut alors appeler search_wiki comme un outil natif.

4. Vibe-coded scripts

Au fur et à mesure, vous découvrez des besoins spécifiques. Demandez à Claude de coder des petits scripts :

Exemple : Trouver les pages les plus citées

# cited-pages.sh
#!/bin/bash
grep -r "\[\[wiki/" wiki/ | cut -d'[' -f3 | cut -d']' -f1 | sort | uniq -c | sort -rn | head -20

Exemple : Générer un rapport hebdomadaire

Claude, crée un script qui génère un rapport hebdomadaire du wiki :
- Pages créées cette semaine
- Pages mises à jour
- Nouveaux liens
- Top 5 des pages les plus liées

Claude le code, vous l'ajoutez à votre ~/.local/bin/.

Intégrer les scripts dans les skills

Pour aller plus loin, embedez les scripts directement dans vos SKILL.md. Ainsi le skill est autonome : il définit la règle ET l'outil pour l'exécuter.

Voici ce que contiendrait .claude/skills/wiki-update/SKILL.md :

## Hash computation

Avant de décider si une source doit être réingérée, calcule son hash avec :

    #!/bin/bash
    # usage: ./hash_source.sh pages/kubernetes.md
    shasum -a 256 "$1" | awk '{print $1}'

Compare le résultat avec la valeur `content_hash` dans `_manifest.json`.
Si identique → skip. Si différent ou absent → réingérer.

> ⚠️ Ne jamais inférer ou "estimer" un hash. Toujours exécuter ce script.

Ce pattern garantit que le skill sera reproductible même si vous changez de modèle ou d'environnement.

5. Graphviz pour visualisations

Générez des graphes du wiki :

# Installation
brew install graphviz

Claude, génère un graphe DOT du thème subrik

Claude crée wiki/visualizations/subrik-graph.dot:

digraph subrik {
  "kubernetes-3488" -> "helm";
  "kubernetes-3488" -> "kubectl";
  "helm" -> "charts";
  "kubectl" -> "kube-config";
  ...
}

Convertissez en image et ouvrez :

dot -Tpng wiki/visualizations/subrik-graph.dot -o subrik.png
open subrik.png

Pour une vue plus lisible sur les grands graphes :

# Layout hiérarchique (sfdp pour les graphes denses)
sfdp -Tsvg wiki/visualizations/subrik-graph.dot -o subrik.svg
open subrik.svg

Évolutions possibles

1. Multi-modal

Logseq supporte les images. Vous pouvez :

Ingérer des PDFs avec images
Demander à Claude de décrire les figures
Référencer les images dans le wiki

## Schéma de l'architecture

![Architecture](../assets/architecture-diagram.png)

^ref-architecture-img

Description (par Claude):
Le diagramme montre 3 couches empilées...

3. Collaboration d'équipe

Le wiki peut être partagé :

Fork personnel : Chaque personne a sa branche
Wiki central : Branch main partagée
Pull requests : Les découvertes individuelles sont proposées à l'équipe
Review : L'équipe valide avant merge

Logseq + Git = Wiki équipe maintenu par LLMs, validé par humains.

4. Export vers autres formats

Le wiki est en markdown. Vous pouvez :

Exporter en slides (Marp)
Générer un site static (MkDocs, Docusaurus)
Créer des PDFs structurés
Produire des Anki decks pour apprentissage

5. Spécialisation par domaine

Créez plusieurs wikis spécialisés :

~/Logseq-Research/    # Recherche académique
~/Logseq-Work/        # Veille pro
~/Logseq-Personal/    # Développement personnel
~/Logseq-Hobbies/     # Passions

Chacun avec son propre schema adapté au domaine.

6. MCP Logseq pour validation du rendu

Un MCP server Logseq exposerait le rendu natif de Logseq à Claude. Cas d'usage : après avoir généré un diagramme Mermaid ou un tableau complexe, Claude pourrait vérifier que le contenu s'affiche correctement dans Logseq avant de le committer — pas juste que la syntaxe markdown est valide, mais que le rendu visuel est cohérent. À surveiller comme évolution de l'écosystème.

Pièges à éviter

1. Autorité aveugle

Le wiki est généré par IA. Vérifiez les faits importants en remontant aux sources.

Solution :

Système de confiance (high/medium/low)
Workflow de review pour faits critiques
Liens systématiques vers sources primaires

2. Drift sémantique

Sur des centaines de pages, le sens des concepts peut dériver.

Solution :

Lint réguliers
Glossaire central avec définitions canoniques
Page meta wiki/conventions.md

3. Explosion combinatoire

Créer une page pour chaque micro-concept → wiki illisible.

Solution :

Guidelines de granularité
Seuil : concept mentionné dans ≥3 sources → page dédiée
Sinon, reste une section dans une page parent

4. Contradictions non résolues

Le wiki accumule des contradictions sans les résoudre.

Solution :

Dossier wiki/contradictions/
Flag has-contradiction: true dans frontmatter
Review périodique des contradictions

5. Orphelins

Pages créées puis jamais relues ni connectées.

Solution :

Lints automatiques
Métrique de densité de liens
Objectif : density > 2 (moyenne 2+ liens par page)

Conclusion

Vous avez maintenant toutes les clés pour construire votre propre Wiki LLM avec Logseq et Claude Code :

Installation : 7 étapes pour setup complet
Workflows : 7 workflows quotidiens maîtrisés
Outils : CLI tools optionnels pour scale
Évolutions : Pistes pour aller plus loin
Pièges : Comment les éviter

Le système devient un second cerveau qui accumule, structure, connecte et synthétise votre connaissance — et évolue avec vous.

Prochaines étapes :

Installer Logseq et créer les 9 skills
Ingérer vos premières sources
Poser vos premières questions
Observer le wiki s'enrichir au fil du temps

"Logseq est l'IDE ; Claude est le programmeur ; votre connaissance est le codebase."

Ressources

Le Wiki LLM : Une révolution dans la gestion de la connaissance

yohann streibel — Fri, 24 Apr 2026 13:42:46 +0000

Le problème avec le RAG classique

La plupart des systèmes RAG (Retrieval Augmented Generation) fonctionnent ainsi :

Vous uploadez des documents
Ils sont découpés en chunks et vectorisés
À chaque question, le LLM récupère les chunks pertinents
Il génère une réponse à partir de ces fragments

Le problème ? Le LLM redécouvre tout depuis zéro à chaque fois. Pas d'accumulation. Pas de synthèse progressive.

Demandez "Comment X se connecte à Y en tenant compte de Z ?" et le LLM doit :

Retrouver les fragments pertinents dans 5 documents différents
Reconstituer le contexte
Faire les connexions
Générer la réponse

Et la prochaine fois que vous posez une question similaire ? Il recommence tout.

La révélation de Karpathy : Le Wiki LLM

Andrej Karpathy (ex-directeur AI chez Tesla et OpenAI) a récemment partagé une approche différente :

"Au lieu de simplement récupérer depuis des documents bruts au moment de la requête, le LLM construit et maintient incrémentalement un wiki persistant — une collection structurée et interconnectée de fichiers markdown."

Le pipeline en 5 étapes

L'architecture complète ressemble à ça :

MAIN PIPELINE (de gauche à droite) :

┌─────────────┐      ┌─────────────┐      ┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   SOURCES   │─────▶│    raw/     │─────▶│    WIKI     │─────▶│  Q&A Agent  │─────▶│   OUTPUT    │
│             │ index│             │ LLM  │             │ query│             │render│             │
│ articles    │      │ unprocessed │      │ .md KB      │      │ complex Q   │      │ markdown    │
│ papers      │      │ files       │      │ summaries   │      │ against     │      │ slides      │
│ repos       │      │ stored as-is│      │ backlinks   │      │ full wiki   │      │ plots       │
│ datasets    │      │ local images│      │ concepts    │      │ no RAG      │      │             │
│ images      │      │             │      │ auto-index  │      │ needed      │      │             │
└─────────────┘      └─────────────┘      └─────────────┘      └─────────────┘      └─────────────┘
                                                 │    ▲
                                                 │    │ filed back
                                                 │    │ knowledge
                                                 │    │ compounds
                                                 └────┘

SUPPORT LAYER (outils connectés au wiki) :

Logseq : IDE frontend pour visualiser raw + wiki, graphe de connaissance
Lint + Heal : Détecte incohérences (liens cassés, pages orphelines) et propose des corrections (créer pages manquantes, réparer liens)
CLI Tools : Primitives utilisées par Claude Code (grep, read, glob) + outils optionnels avancés (qmd pour recherche sémantique, Web UI, MCP servers - voir section dédiée plus loin)

Les trois couches

1. Raw Sources : Vos documents sources, jamais modifiés par l'IA. C'est votre source de vérité.

Articles, papers, repos, datasets
Images et diagrammes
Notes de podcasts, vidéos
Structure : pages/, journals/, assets/

2. Le Wiki : L'IA possède entièrement cette couche (~100 articles / ~400K mots pour un wiki mature).

Fichiers .md avec propriétés Logseq natives
Summaries avec backlinks
Concept categories
Auto-maintained index
Structure : wiki/[thème]/[page].md

3. Le Schema : Skills Claude Code qui définissent :

Format des pages wiki (propriétés Logseq)
Workflows (setup, ingest, update, query, lint)
Primitives de lecture optimisées
Gestion du manifest et du log
Structure : .claude/skills/logseq-*/SKILL.md

Pourquoi ça marche ?

La partie pénible d'une base de connaissance n'est pas la lecture ou la réflexion — c'est la maintenance.

Mettre à jour les références croisées
Garder les résumés à jour
Noter quand de nouvelles données contredisent les anciennes
Maintenir la cohérence sur des dizaines de pages

Les humains abandonnent les wikis parce que le coût de maintenance croît plus vite que la valeur.

Les LLM ne s'ennuient jamais. Ils peuvent lire et modifier 15 fichiers en une passe sans problème. Le wiki reste maintenu parce que le coût de maintenance est proche de zéro.

Pourquoi Logseq dans cet article ?

Le concept de Wiki LLM fonctionne avec n'importe quel outil de notes : Obsidian, Logseq, Notion, voire des fichiers markdown simples.

Cet article utilise Logseq simplement parce que c'est l'outil que j'utilise au quotidien. Le gist original de Karpathy utilise Obsidian, et il existe une excellente implémentation pour Obsidian (obsidian-wiki) dont on s'inspire ici.

L'important n'est pas l'outil, c'est le concept : un wiki markdown maintenu par un LLM qui s'enrichit au fil du temps.

Quelques particularités de Logseq utilisées dans cette implémentation :

Graphe de connaissance natif : chaque [[lien]] crée automatiquement un backlink
Références de blocs : ((block-id)) pour traçabilité granulaire — et c'est plus qu'une question de style. La structure outliner de Logseq découpe chaque page en blocs hiérarchiques (parent/enfant). Le wiki peut ainsi citer un paragraphe précis d'une source plutôt qu'une page entière. Lors d'une requête, Claude n'a pas besoin de relire 50 lignes pour retrouver l'information : il grep l'identifiant de bloc, lit uniquement ce bloc et ses enfants directs. Résultat : un graphe de connaissance plus granulaire, des citations plus précises, et une consommation de tokens réduite à chaque interrogation.
Propriétés : title::, summary::, sources:: (équivalent du frontmatter YAML)
Journal quotidien : structure journals/YYYY-MM-DD.md par défaut
Queries Datalog : vues dynamiques sur la connaissance

Visualisation du graphe de connaissance : le wiki au centre avec toutes les pages interconnectées

Mais vous pouvez adapter ce système à votre outil préféré en modifiant les skills Claude Code pour qu'ils utilisent la syntaxe de votre outil.

Architecture technique détaillée

Avant de plonger dans l'installation, comprenez l'architecture système. Le wiki repose sur 9 skills Claude Code orchestrés autour d'un manifest JSON et d'un log markdown.

Le système de tracking : manifest + log + hashing

`wiki/_manifest.json` — État du wiki

{
  "version": 1,
  "created_at": "2026-04-10T10:00:00Z",
  "last_ingest": "2026-04-10T15:30:00Z",
  "stats": {
    "total_sources_ingested": 47,
    "total_pages_created": 123
  },
  "sources": {
    "pages/kubernetes.md": {
      "ingested_at": "2026-04-10T15:30:00Z",
      "content_hash": "a8f5f167f44f4964e6c998dee827110c284a0dd2",
      "pages_created": ["wiki/kubris/kubernetes-3488"],
      "pages_updated": ["wiki/kubris/_index"]
    }
  }
}

Le hash SHA-256 : Chaque source a un hash de son contenu. Lors d'un update, Claude recalcule le hash. Si identique → skip (pas de changement). Si différent → source modifiée, on réingère.

`wiki/_log.md` — Journal des opérations

## Log

- [2026-04-10T10:00:00Z] SETUP — initialisation du wiki, 5 thèmes détectés
- [2026-04-10T15:30:00Z] INGEST — 47 sources ingérées, 123 pages créées
- [2026-04-10T16:15:00Z] UPDATE — 3 sources modifiées, 8 pages mises à jour
- [2026-04-11T09:00:00Z] LINT — 2 liens cassés détectés, 1 page orpheline
- [2026-04-11T09:05:00Z] CROSS-LINK — 45 liens ajoutés

Append-only, parseable avec des outils Unix standard :

grep "^- \[" wiki/_log.md | tail -5  # Les 5 dernières opérations

Les 9 skills Claude Code

Les skills sont des fichiers SKILL.md dans .claude/skills/logseq-*/. Claude les invoque selon le contexte.

Skill	Trigger	Fonction principale
logseq-llm-wiki	Fondation	Définit syntaxe Logseq (`title::`, `[[liens]]`, `((block-refs))`), format wiki, primitives optimisées (Grep avant Read), structure manifest + log
logseq-setup	"initialise mon wiki"	Détecte thèmes, crée structure `wiki/` avec `_master-index.md`, `_log.md`, `_manifest.json`
logseq-ingest	"ingère mon vault"	Inventorie sources, distille pages/journaux/assets en pages wiki, met à jour index/manifest/log. Modes append (skip si hash inchangé) ou full
logseq-update	"mets à jour"	Compare hash sources vs manifest, traite modifiées/nouvelles (merge intelligent), signale supprimées
logseq-query	Questions utilisateur	Grep sur wiki d'abord, puis pages/journaux si besoin, lecture ciblée, réponse avec citations `[[]]`
logseq-status	"statut de mon wiki"	Dashboard : stats sources/wiki, delta (modifiées/nouvelles), suggestions d'actions
logseq-lint	"vérifie mon wiki"	Détecte liens cassés, pages orphelines, sources supprimées, propriétés manquantes, tâches NOW orphelines
logseq-rebuild	"rebuild"	Archive `wiki/` vers `_archive/DATE/`, réinitialise manifest/log, propose re-ingest (confirmation obligatoire)
logseq-cross-linker	"tisse les liens"	Détecte mentions non linkées, ajoute `[[]]`, vérifie bidirectionnalité, enrichit le graphe de connaissance

Le Core Insight

"You never write the wiki. The LLM writes everything. You just steer — every answer compounds."

Vous ne touchez jamais wiki/ manuellement. Vous :

Ajoutez des sources dans pages/ ou journals/
Posez des questions
Demandez des updates, des lints, des cross-links

Claude écrit, maintient, enrichit. Chaque réponse améliore le wiki. Compounding knowledge.

Cas d'usage réels

Voyons quelques scénarios concrets d'utilisation du système.

1. Recherche académique

Contexte : Doctorant en ML, lit 5-10 papers par semaine.

Structure Logseq :

pages/
  papers-2026/
    attention-is-all-you-need.md
    llama-3-paper.md
    ...
journals/
  2026-04-10.md   # Notes de lecture quotidiennes
wiki/
  ml/
    transformers.md
    attention-mechanism.md
    positional-encoding.md
  _master-index.md

Workflow :

Lit un paper, prend des notes dans journals/
Fin de semaine : Claude, mets à jour mon wiki
Claude extrait concepts, enrichit pages existantes
Demande synthèse : Quelle est l'évolution de l'attention de 2017 à 2024 ?
Claude génère une page de synthèse avec timeline

2. Self-improvement et journalisation

Contexte : Pratique la tenue d’un journal quotidien pour favoriser ton développement personnel.

Structure :

journals/
  2024-01-01.md   # 365 jours de journal
  ...
  2024-12-31.md
wiki/
  personal-growth/
    productivity-patterns.md
    decision-frameworks.md
    learning-insights.md

Workflow :

Journal quotidien dans Logseq (habitudes, réflexions, décisions)
Tous les mois : Claude, distille mes journaux du mois dernier
Claude identifie patterns récurrents, crée pages thématiques
Fin d'année : Quels sont mes 5 apprentissages majeurs ?

3. Veille technologique

Contexte : Développeur qui suit 20+ blogs tech.

Structure :

pages/
  articles/
    kubernetes-best-practices.md
    rust-async-guide.md
    ...
wiki/
  kubris/
    kubernetes.md
    helm.md
  rust/
    async-programming.md

Workflow :

Clippe articles web vers Logseq (extension Logseq Web Clipper)
Chaque semaine : Claude, ingère les nouveaux articles
Demande connections : Comment Rust async se compare à Go goroutines ?
Cross-link automatique entre concepts

4. Lecture de livres

Contexte : Lit des livres techniques chapitre par chapitre.

Structure :

pages/
  books/
    designing-data-intensive-applications.md  # Notes par chapitre
journals/
  2026-04-10.md  # "Terminé chapitre 5 sur replication"
wiki/
  databases/
    replication.md
    consistency.md
    cap-theorem.md

Workflow :

Notes de lecture dans pages/books/
À la fin de chaque partie : Claude, distille les chapitres 1-5
Claude crée pages de concepts avec citations précises
Fin du livre : Génère un graphe des concepts du livre

Inspiration : le projet Obsidian Wiki

Le projet obsidian-wiki d'Ar9av est une excellente implémentation du concept Wiki LLM pour Obsidian. Cette approche Logseq s'en inspire largement en adaptant :

La structure des skills : même logique (setup, ingest, update, query, lint)
Le système de tracking : manifest JSON + log markdown
Les primitives optimisées : Grep avant Read pour minimiser les tokens
La philosophie : le LLM écrit tout, vous ne faites que guider

La principale différence est l'adaptation à la syntaxe et aux fonctionnalités natives de Logseq (propriétés :: au lieu de YAML frontmatter, block-refs ((id)), queries Datalog, etc.).

Si vous utilisez Obsidian, je vous recommande fortement le projet obsidian-wiki original. Si vous utilisez Logseq, suivez cette approche. Le concept reste le même : un wiki markdown enrichi et maintenu par un LLM.

Métriques de succès

Comment savoir si votre wiki fonctionne ?

Quantitatif

Métrique	Mauvais	Moyen	Bon	Excellent
Densité de liens	< 1	1-2	2-4	> 4
Taux d'orphelins	> 20%	10-20%	5-10%	< 5%
Sources par concept	< 1.5	1.5-2.5	2.5-4	> 4
Temps de réponse*	> 5min	2-5min	30s-2min	< 30s
Taux de contradiction	> 10%	5-10%	2-5%	< 2%

* Pour une question typique nécessitant ≥3 sources

Qualitatif

Serendipité : Découvrez-vous des connexions inattendues en naviguant ?
Confiance : Faites-vous confiance aux réponses du wiki ?
Accumulation : Sentez-vous que votre connaissance s'accumule ?
Maintenance : Le wiki reste-t-il cohérent sans effort manuel ?

Conclusion

Le pattern "Wiki LLM" de Karpathy transforme le RAG passif en base de connaissance vivante :

Accumulation : Chaque source enrichit définitivement le wiki
Synthèse : Les connexions sont compilées, pas redécouvertes
Maintenance zéro : L'IA fait le bookkeeping pénible
Compounding : La valeur croît exponentiellement

Avec Logseq et Claude Code, vous avez un système qui devient un second cerveau — non seulement il stocke l'information, mais il la structure, la connecte, la synthétise, et évolue avec vous.

"Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase."

— Andrej Karpathy

Ou dans notre cas :

"Logseq est l'IDE ; Claude est le programmeur ; votre connaissance est le codebase."

Prêt à passer à l'action ? Consultez l'article suivant : Guide pratique : Implémenter votre Wiki LLM avec Logseq et Claude Code qui paraitra la semaine prochaine ;).

Ressources

DevOps Rex 2025 : Retour sur deux jours de conférences

yohann streibel — Mon, 15 Dec 2025 10:38:52 +0000

10-11 décembre 2025 — Cité des Sciences, Paris

La 6ᵉ édition de DevOps Rex a rassemblé la communauté DevOps francophone pour deux jours de retours d'expérience 100% terrain. L'événement s'est tenu en parallèle du salon Open Source Experience, le rendez-vous européen des solutions open source. Les participants pouvaient ainsi alterner entre les conférences DevOps Rex et les stands de présentation des éditeurs de logiciels open source dans l'espace Solutions.

Programme des talks

Jour 1 — Mercredi 10 décembre

Horaire	Talk	Intervenant
10h10 - 10h30	Codeshift : Démarche DevSecOps chez les Ops de BPCE-IT	Julien Fouqueray, Clément Rochas (BPCE-IT)
10h30 - 11h00	Engineering Platform boostée à l'IA : ok mais pour quoi faire ?	Matthieu Vincent (Sopra Steria)
11h30 - 12h00	Comment nous avons mis en place la pratique DevSecOps chez Orange	Girija Saint-Ange, Cédric Olivier (Orange)
12h00 - 12h15	Confiance opérationnelle : quand Sécurité et Delivery co-conçoivent les modèles d'accès	Isabelle Kraemer (Datadog)
14h00 - 14h25	Keynote : La géopolitique du numérique	Ophélie Coelho (IRIS / CIS - CNRS)
14h25 - 14h55	Quitter AWS : une migration vers le cloud souverain (presque) sans douleur	Jérôme Galais (Kaliop)
14h55 - 15h25	Migration de la plateforme Data de Matmut sur le cloud S3NS	Pascal Deshayes (TerraOps), Jean-Jacques Mok (Matmut)

Jour 2 — Jeudi 11 décembre

Horaire	Talk	Intervenant
10h05 - 10h25	L'importance du contexte en IA x Infra : Votre infrastructure est un graphe	Roxane Fischer (Anyshift.io)
10h30 - 11h00	Agentic AI : Et si c'était l'IA qui faisait ta code review ?	Oussama Abai, Kenza Barnier (Les Filles & Les Garçons de la Tech)
11h30 - 12h00	Industrialiser un LLMaaS souverain : scalabilité, sécurité… et une IA qui aide à se créer elle-même	Alexandru Lata (Cloud Temple)
12h00 - 12h30	ChatBot/RAG 100% Souverain	Antoine Durand (Accure IT)
14h00 - 14h35	Unifier le delivery legacy et cloud-native : le défi DevOps d'iMSA	Nicolas Cazottes (iMSA)

Focus #1 : Quitter AWS — Migration cloud souverain (Kaliop)

Le coup de cœur de Yohann

Le contexte

Jérôme Galais (Technical Expert DevOps & Cloud chez Kaliop) a présenté l'accompagnement d'une entreprise en forte croissance sur une application de monitoring hébergée sur AWS. L'audit préalable révélait plusieurs problèmes :

Infrastructure AWS plus suffisamment optimisée
Plusieurs clusters Elasticsearch sur instances EC2
Utilisation d'AWS Kinesis pour la brique temps réel
Application Python utilisant beaucoup de ressources
Portabilité de code limitée
Empilement de dette technique dû à une forte croissance

Contrainte majeure : réduire les coûts de 50%.

Les chiffres de la plateforme

Métrique	Valeur
Utilisateurs	80 000
Clients actifs	22 000
Clés Redis	6 millions
Opérations/seconde	1 000
Bande passante moyenne	10 Go

La solution : Scaleway avec bare metal + services managés

L'équipe a migré d'AWS vers Scaleway, adoptant une architecture hybride combinant services managés et serveurs physiques (ElasticMetal) :

Services managés (Scaleway) : Load balancer, Kubernetes, Queues managées, Base de données, Stockage Objet

Serveurs physiques (ElasticMetal) : Rancher (downstream clusters) avec ElasticSearch et Kafka

L'utilisation de bare metal plutôt que des instances managées permet de bénéficier d'une bande passante de 10 Gb/s pour un coût 25% moins élevé.

Résultat

La migration a été réalisée en 4 mois avec une équipe de 3 personnes à temps plein, pour un coût projet d'environ une centaine de milliers d'euros.

Le gain financier est significatif : la facture mensuelle est passée de ~50 000 €/mois à ~20 000 €/mois, soit une réduction de plus de 50% des coûts d'hébergement.

À noter : la présentation de Jérôme Galais s'est distinguée par son aisance, son rythme soutenu et une touche d'humour bienvenue qui a rendu le retour d'expérience particulièrement agréable à suivre.

Ce retour d'expérience est détaillé dans un article dédié : Retour d’expérience : comment Plecto a migré sa plateforme cloud-to-cloud d’un hyperscaler vers Scaleway.

Focus #2 : ChatBot/RAG 100% Souverain (Accure IT)

Le coup de cœur d'Antonin

Le constat de départ

Antoine Durand, Architecte Data & Cloud chez Accure IT, a ouvert sa présentation sur un chiffre marquant : 70 à 88% des POC IA ne passent jamais en production (source : IDC/Lenovo & McKinsey 2025). La raison ? Manque d'industrialisation et ROI non démontré. Un constat qui illustre bien la "FOMO de l'IA" actuelle : cette peur de rater le train de l'intelligence artificielle qui pousse les organisations à lancer des projets sans toujours anticiper leur passage en production.

Le contexte client

Début 2025, un client dans les Énergies Renouvelables contacte Accure IT en exigeant la signature d'un NDA avant même d'entamer les discussions. L'enjeu : exploiter un immense pool de données non structurées (doc, docx, pdf, images, xls...) pour améliorer les process R&D (veille technologique, brevets) et le support (questions/réponses instantanées).

Contrainte absolue : 100% souverain, 100% français, sans exposition au Cloud Act ou Patriot Act. Exit donc les hyperscalers classiques (Azure, AWS, Google). Cela s'explique par le fait que leur propriété intellectuelle est leur coeur de métier.

L'approche technique

Accure IT a relevé le défi en mettant en production une v1 dès juillet 2025, hébergée sur Clever Cloud.

Stack technique :

Hosting PaaS : Clever Cloud (Docker + S3)
Frontend : StreamLit / Python
Base vectorielle : Postgres 17 + pgVector
Versionning : Heptapod (GitLab open source)
LLM : Mistral AI (Embed + AI) via API
Orchestration : Airflow 3

L'architecture repose sur un pipeline RAG classique : ingestion des documents, vectorisation, stockage dans une base de connaissances, puis interrogation via le chatbot connecté à Mistral AI.

Les axes du retour d'expérience

La présentation a couvert quatre dimensions clés : la gouvernance et souveraineté (faire du "made in France, hosted in France" à la pointe), la stack IA en production, les pratiques DevOps/DataOps pour la CI/CD et le cycle de vie de la data, et enfin le FinOps pour contenir les coûts tout en assurant le service.

Les tendances clés de l'édition 2025

IA intégrée au cycle DevOps — Sopra Steria a présenté sa vision "Agentic AI in the Software Delivery Lifecycle" avec des agents IA (Maia, heiDI, DEP.AI) intervenant à chaque étape : définition des requirements, user stories, architecture, tests, code review.

Souveraineté numérique — Plusieurs talks ont abordé les alternatives aux hyperscalers américains, que ce soit via bare metal ou cloud providers français comme Scaleway ou Clever Cloud.

Grilles de maturité DevSecOps — BPCE a partagé sa grille de maturité "à la Nutriscore" (ABCDE) pour mesurer et accompagner la progression des équipes sur 4 axes : Craft, CI, CD, Sécurité.

Attention à la dette Kubernetes — Message récurrent : mettre à jour régulièrement, ne pas tout containériser, refactoriser tôt pour éviter les "macroservices".

À retenir

DevOps Rex 2025 confirme la maturité de l'écosystème DevOps français. L'IA s'invite désormais à chaque étape du cycle, la souveraineté devient un critère de choix assumé, et les retours d'expérience partagés montrent des organisations qui n'hésitent plus à remettre en question leurs choix d'infrastructure.

Rendez-vous en 2026.

Pour vous donner envi de venir à de l'événement 2026, voici la playlist des vidéos de l'édition 2025 :

Vous pouvez nous retrouver sur les réseaux sociaux - LinkedIn Antonin Brugnot et Yohann Streibel - pour plus de retours et discussions autour des sujets DevOps !

🚀 SWAG : Le Reverse Proxy Docker qui va révolutionner votre homelab !

yohann streibel — Sun, 07 Dec 2025 08:14:22 +0000

Salut les dev ! 👋

Aujourd'hui, je vais vous parler d'un outil qui a littéralement transformé ma façon de gérer mes services web : SWAG (Secure Web Application Gateway). Si vous êtes dans le monde du homelab ou si vous déployez plusieurs services web, cet article va vous intéresser !

Table des matières

Mais qu'est-ce que SWAG exactement ?
Pourquoi SWAG plutôt qu'autre chose ?
Notre architecture cible
Configuration réseau et DNS (étape cruciale !)
- 4.1 Configuration chez votre provider (exemple Free)
- 4.2 Configuration DuckDNS
- 4.3 Vérification IP publique
- 4.4 Test de connectivité
Installation avec Docker Compose
Configuration étape par étape
- 6.1 Préparation des variables d'environnement
- 6.2 Configuration DuckDNS automatique
- 6.3 Premiers pas après démarrage
- 6.4 Structure des dossiers créés
Ajouter nos premiers services
- 7.1 Service 1 : Home Assistant
- 7.2 Configuration du proxy dans SWAG
- 7.3 Test de votre configuration
Troubleshooting réseau
Tips et bonnes pratiques
- 9.1 Réseau Docker dédié
- 9.2 Gestion des logs
- 9.3 Test de configuration
- 9.4 Wildcard certificates
Sécurisation avec Authelia (bonus)
Résultat final
Debugging courant
Conclusion
Pour aller plus loin

🤔 Mais qu'est-ce que SWAG exactement ?

SWAG, c'est un reverse proxy tout-en-un basé sur nginx qui gère automatiquement vos certificats SSL Let's Encrypt. En gros, c'est votre portier numérique qui :

🔒 Sécurise automatiquement vos services avec des certificats SSL
🌐 Expose vos services Docker sur des sous-domaines propres
🛡️ Protège vos applications avec une authentification centralisée
📋 Gère tout ça avec de la configuration simple

💭 Pourquoi SWAG plutôt qu'autre chose ?

Avant SWAG, j'utilisais nginx classique avec certbot... Quelle galère ! 😅 Entre les renouvellements de certificats qui plantent, les configs nginx à maintenir manuellement, et la gestion des domaines, c'était un vrai casse-tête.

SWAG résout tout ça d'un coup :

Certificats wildcard automatiques
Configs pré-faites pour les services populaires
Intégration native avec Docker
Support de l'authentification (Authelia, OAuth, etc.)

🏗️ Notre architecture cible

Imaginons qu'on veuille exposer plusieurs services :

Un Home Assistant sur homeassistant.mondomaine.fr
Un serveur de fichiers sur files.mondomaine.fr
Une interface d'administration sur admin.mondomaine.fr

Avec SWAG, tout passe par un seul point d'entrée sécurisé !

🌐 Configuration réseau et DNS (étape cruciale !)

Avant de plonger dans Docker, il faut préparer le terrain côté réseau. C'est souvent l'étape que les débutants oublient ! 😅

1. Configuration chez votre provider (exemple Free)

Chez Free, il faut :

Se connecter à l'interface Freebox : http://mafreebox.freebox.fr
Aller dans "Paramètres de la Freebox" > "Gestion des ports"
Créer une redirection de port :
- Port externe : 443 (HTTPS)
- Port interne : 443
- IP destination : IP locale de votre serveur (ex: 192.168.1.100)
- Protocole : TCP
Optionnel : Port 80 pour les redirections HTTP vers HTTPS :
- Port externe : 80
- Port interne : 80
- IP destination : 192.168.1.100

💡 Tip sécurité : Au lieu d'exposer directement les ports 80/443, vous pouvez utiliser des ports custom (ex: 8443) et faire la redirection. Plus sécurisé !

2. Configuration DuckDNS

DuckDNS, c'est le DNS dynamique gratuit parfait pour les homelabs !

Inscription sur duckdns.org
Créer votre domaine : monhomelab.duckdns.org
Noter votre token (on en aura besoin dans Docker)

💡 Alternative DNS providers : DuckDNS n'est pas obligatoire ! SWAG supporte plein d'autres providers :

Gratuits :

DuckDNS (duckdns) - Le plus simple pour débuter

FreeDNS (freedns) - Autre alternative gratuite

No-IP (noip) - Service populaire avec version gratuite

Payants (mais plus pro) :

Cloudflare (cloudflare) - Excellent, rapide et pas cher

OVH (ovh) - Provider français

Gandi (gandi) - Interface simple

Route53 (route53) - AWS, très fiable

DigitalOcean (digitalocean) - Simple à utiliser

Namecheap (namecheap) - Bon rapport qualité/prix

Configuration type pour Cloudflare :
environment:
  - URL=mondomaine.com
  - VALIDATION=dns
  - DNSPLUGIN=cloudflare
  - EMAIL=votre-email@example.com
  - CLOUDFLARETOKEN=votre-api-token-cloudflare
La liste complète est dispo dans la doc SWAG ! 📚

3. Vérification IP publique

Votre DuckDNS doit pointer vers votre IP publique :

# Vérifier votre IP publique
curl ifconfig.me

# Vérifier que DuckDNS pointe bien dessus
nslookup monhomelab.duckdns.org

Si les IPs correspondent, c'est bon ! 🎯

4. Test de connectivité

Avant même de démarrer SWAG, testez que le port forwarding fonctionne :

# Sur votre serveur local, démarrez un serveur web simple
python3 -m http.server 8080

# Depuis l'extérieur, testez avec votre domaine
curl http://monhomelab.duckdns.org:8080

Si ça marche, vous êtes prêts pour SWAG !

📦 Installation avec Docker Compose

Première étape : créer notre docker-compose.yml pour SWAG.

version: "3.8"

networks:
  web-proxy:
    external: false

services:
  swag:
    image: lscr.io/linuxserver/swag:latest
    container_name: swag
    cap_add:
      - NET_ADMIN
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Paris
      - URL=monhomelab.duckdns.org  # Votre domaine DuckDNS
      - VALIDATION=duckdns          # Validation via DuckDNS
      - DUCKDNSTOKEN=12345678-1234-1234-1234-123456789012  # Votre token DuckDNS
      - SUBDOMAINS=wildcard         # Permet *.monhomelab.duckdns.org
      - EMAIL=votre-email@example.com
      - ONLY_SUBDOMAINS=false       # Important pour que le domaine principal marche
    volumes:
      - ./swag/data:/config
    ports:
      - "80:80"     # HTTP (redirections vers HTTPS)
      - "443:443"   # HTTPS (vos services sécurisés)
    networks:
      - web-proxy
    restart: unless-stopped

🔧 Configuration étape par étape

1. Préparation des variables d'environnement

Les variables importantes à comprendre :

URL : Votre domaine complet (DuckDNS, Cloudflare, ou autre provider)
VALIDATION=duckdns : Type de validation selon votre provider (voir liste ci-dessus)
SUBDOMAINS=wildcard : Génère un certificat pour tous vos sous-domaines
DUCKDNSTOKEN : Token/API key de votre provider DNS
ONLY_SUBDOMAINS=false : Permet d'utiliser le domaine principal aussi

💭 Pourquoi DuckDNS dans cet exemple ? C'est gratuit et ultra simple pour débuter ! Mais si vous avez déjà un domaine chez Cloudflare/OVH/Gandi, utilisez-le directement.

2. Configuration DuckDNS automatique

SWAG va automatiquement :

Mettre à jour votre IP sur DuckDNS
Valider votre domaine via l'API DuckDNS
Générer le certificat wildcard
Renouveler automatiquement tout ça !

C'est la magie de cette combo SWAG + DuckDNS ! ✨

3. Premiers pas après démarrage

# Démarrer SWAG
docker-compose up -d swag

# Vérifier les logs
docker logs swag

# Vous devriez voir quelque chose comme :
# "Server ready"
# "Certificate renewal successful"

4. Structure des dossiers créés

Après le premier démarrage, SWAG crée cette structure :

swag/data/
├── nginx/
│   ├── nginx.conf
│   ├── site-confs/
│   └── proxy-confs/     # ← Les configs de nos services !
├── keys/
│   └── letsencrypt/     # ← Nos certificats SSL
└── log/

🎯 Ajouter nos premiers services

Service 1 : Home Assistant

Créons notre service Home Assistant dans le même réseau :

# Ajout dans docker-compose.yml
  homeassistant:
    image: homeassistant/home-assistant:stable
    container_name: homeassistant
    environment:
      - TZ=Europe/Paris
    volumes:
      - ./homeassistant/data:/config
    networks:
      - web-proxy
    ports:
      - "8123:8123"  # Optionnel, pour accès direct local
    restart: unless-stopped

Configuration du proxy dans SWAG

Créer le fichier : swag/data/nginx/proxy-confs/homeassistant.subdomain.conf

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name homeassistant.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    location / {
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app homeassistant;
        set $upstream_port 8123;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    }

    # Support des WebSockets (important pour Home Assistant !)
    location /api/websocket {
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app homeassistant;
        set $upstream_port 8123;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Test de votre configuration

Une fois tout configuré, testez vos URLs :

✅ https://monhomelab.duckdns.org → Page par défaut SWAG
✅ https://homeassistant.monhomelab.duckdns.org → Votre Home Assistant
✅ Certificat SSL valide et wildcard !

🔧 Troubleshooting réseau

Problème : "Site inaccessible depuis l'extérieur"

Vérifiez votre IP publique :

# Sur votre serveur
curl ifconfig.me

# Doit correspondre à :
nslookup monhomelab.duckdns.org

Testez le port forwarding :

# Depuis l'extérieur (4G par exemple)
telnet monhomelab.duckdns.org 443

Vérifiez les logs SWAG :

docker logs swag | grep -i "certificate\|error\|duckdns"

Problème : "DuckDNS validation failed"

Vérifiez votre token DuckDNS :

# Test manuel de l'API DuckDNS
curl "https://www.duckdns.org/update?domains=monhomelab&token=VOTRE_TOKEN&ip="

Doit retourner "OK" si le token est bon.

Problème : "Certificat non généré"

Souvent c'est un souci de timing. DuckDNS peut mettre quelques minutes à propager :

# Redémarrez SWAG après quelques minutes
docker restart swag

# Surveillez les logs
docker logs -f swag

🔥 Tips et bonnes pratiques

1. Réseau Docker dédié

Créez toujours un réseau dédié pour vos services web :

# Créer le réseau manuellement
docker network create web-proxy

# Ou le définir comme external dans docker-compose
networks:
  web-proxy:
    external: true

2. Gestion des logs

Surveillez les logs pour déboguer :

# Logs SWAG en temps réel
docker logs -f swag

# Logs nginx spécifiques
docker exec swag tail -f /config/log/nginx/error.log

3. Test de configuration

Avant de redémarrer, testez toujours :

# Test de la config nginx
docker exec swag nginx -t

# Rechargement à chaud (si test OK)
docker exec swag nginx -s reload

4. Wildcard certificates

Avec les certificats wildcard, vous pouvez ajouter autant de sous-domaines que vous voulez sans renouveler le certificat !

🛡️ Sécurisation avec Authelia (bonus)

Pour aller plus loin, on peut ajouter une authentification centralisée :

# Service Authelia
  authelia:
    image: authelia/authelia:latest
    container_name: authelia
    volumes:
      - ./authelia/data:/config
    networks:
      - web-proxy
    environment:
      - TZ=Europe/Paris
    restart: unless-stopped

Et dans notre config nginx, on ajoute :

# En haut du fichier de config de service
include /config/nginx/authelia-server.conf;

# Dans la location /
include /config/nginx/authelia-location.conf;

🎯 Résultat final

Une fois tout configuré, vous avez :

✅ https://homeassistant.monhomelab.duckdns.org - Sécurisé avec SSL

✅ https://files.monhomelab.duckdns.org - Protégé par authentification

✅ https://admin.monhomelab.duckdns.org - Accessible uniquement pour les admins

Le tout avec un seul certificat wildcard qui se renouvelle automatiquement !

🐛 Debugging courant

Problème : "502 Bad Gateway"

# Vérifier que le service target existe
docker ps | grep nom-du-service

# Vérifier la résolution DNS interne
docker exec swag nslookup nom-du-service

Problème : Certificat non généré

# Vérifier les logs de génération
docker logs swag | grep -i "certificate\|error\|duckdns"

# Tester manuellement DuckDNS
curl "https://www.duckdns.org/update?domains=VOTRE_DOMAINE&token=VOTRE_TOKEN&ip="

Problème : WebSockets qui ne passent pas

Ajoutez toujours ces headers dans vos configs :

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_cache_bypass $http_upgrade;

🎉 Conclusion

SWAG a vraiment simplifié ma vie de homelabber ! En quelques fichiers de config, j'ai :

Des certificats SSL automatiques
Des sous-domaines propres pour tous mes services
Une authentification centralisée
Une maintenance quasi nulle

Si vous hésitez encore à passer le cap, foncez ! C'est un investissement en temps qui se rentabilise très vite.

🔗 Pour aller plus loin

Et vous, vous utilisez quoi comme reverse proxy ? Dites-moi en commentaire ! 💬

docker #nginx #ssl #homelab #reverseproxy #swag #letsencrypt #devops

DEV Community: yohann streibel

Guide pratique : Implémenter votre Wiki LLM avec Logseq et Claude Code

⚠️ Confidentialité et données sensibles

Installation et configuration

Étape 1 : Installer Logseq

Étape 2 : Structure initiale

Étape 3 : Configuration Logseq

Étape 4 : Installer les plugins Logseq

Étape 5 : Créer les skills Claude Code

Étape 6 : Initialiser le wiki

Étape 7 : Initialiser Git (optionnel mais recommandé)

Workflows quotidiens

Workflow 1 : Première ingestion complète

Workflow 2 : Update incrémental quotidien

Workflow 3 : Poser une question

Workflow 4 : Audit de santé (Lint)

Workflow 5 : Tissage de liens

Workflow 6 : Dashboard de statut

Workflow 7 : Rebuild complet

Exemple concret : Premier jour avec un vault existant

1. Installation (30 min)

2. Initialisation (2 min)

3. Première ingestion (30-45 min pour ~1000 sources)

4. Enrichissement (5 min)

5. Audit (2 min)

6. Utilisation quotidienne

Le Layer "Lint + Heal" : Maintenance automatique

Lint (déjà vu)

Heal (workflow manuel actuellement)

Heal guidé (aujourd'hui)

Recherche web pour données manquantes

CLI Tools optionnels

1. qmd : Moteur de recherche hybride local

2. Web UI pour exploration directe

3. MCP Server pour qmd

4. Vibe-coded scripts

5. Graphviz pour visualisations

Évolutions possibles

1. Multi-modal

3. Collaboration d'équipe

4. Export vers autres formats

5. Spécialisation par domaine

6. MCP Logseq pour validation du rendu

Pièges à éviter

1. Autorité aveugle

2. Drift sémantique

3. Explosion combinatoire

4. Contradictions non résolues

5. Orphelins

Conclusion

Ressources

Le Wiki LLM : Une révolution dans la gestion de la connaissance

Le problème avec le RAG classique

La révélation de Karpathy : Le Wiki LLM

Le pipeline en 5 étapes

Les trois couches

Pourquoi ça marche ?

Pourquoi Logseq dans cet article ?

Architecture technique détaillée

Le système de tracking : manifest + log + hashing

wiki/_manifest.json — État du wiki

wiki/_log.md — Journal des opérations

Les 9 skills Claude Code

Le Core Insight

Cas d'usage réels

1. Recherche académique

2. Self-improvement et journalisation

3. Veille technologique

4. Lecture de livres

Inspiration : le projet Obsidian Wiki

Métriques de succès

Quantitatif

Qualitatif

Conclusion

Ressources

DevOps Rex 2025 : Retour sur deux jours de conférences

Programme des talks

Jour 1 — Mercredi 10 décembre

Jour 2 — Jeudi 11 décembre

Focus #1 : Quitter AWS — Migration cloud souverain (Kaliop)

`wiki/_manifest.json` — État du wiki

`wiki/_log.md` — Journal des opérations