TechradarDev/docs/app/troubleshooting.md

Guide de dépannage

Problèmes courants et solutions

Navigation et liens

Doublons de liens dans la navigation

Symptôme : Plusieurs liens "Équipe" ou autres liens apparaissent en double dans le header.

Causes possibles :

• Le script Python a ajouté le lien plusieurs fois
• Les scripts JavaScript ajoutent encore des liens (fonctions non désactivées)
• Le fichier Navigation.tsx contient déjà des liens dupliqués

Solutions :

1. Vérifier que les fonctions JavaScript sont bien désactivées :
   • public/strategie-script.js : addLinksToHeader() doit être commentée
   • public/strategie-link.js : addStrategyLinkToHeader() doit être commentée
2. Rebuild l'image Docker avec --no-cache pour forcer l'exécution du script Python de nettoyage
3. Vérifier dans les logs Docker que le script Python a bien supprimé les doublons

Vérification :

# Dans le conteneur
grep -c 'href="/team"' .techradar/src/components/Navigation/Navigation.tsx
# Doit retourner 1 (un seul lien)

Lien "Équipe" n'apparaît pas

Symptôme : Le lien "👥 Équipe" n'est pas visible dans la navigation.

Causes possibles :

• Le script Python n'a pas été exécuté
• Le fichier Navigation.tsx n'a pas été trouvé
• Erreur dans le script Python

Solutions :

1. Vérifier les logs Docker lors du build pour voir si le script Python s'est exécuté
2. Vérifier que le fichier .techradar/src/components/Navigation/Navigation.tsx existe
3. Vérifier que le script Python a bien trouvé l'emplacement pour insérer le lien
4. Rebuild avec --no-cache pour forcer l'exécution

Vérification :

# Dans le conteneur
grep 'href="/team"' .techradar/src/components/Navigation/Navigation.tsx
# Doit retourner le lien

Données du radar

Seulement 2 blips affichés (Ansible et OpenTofu)

Symptôme : Le radar n'affiche que quelques blips au lieu de tous.

Causes possibles :

• Les blips utilisent des rings non définis dans la config (core, strategic, support au lieu de adopt, trial, assess, hold)
• Les données business n'ont pas été copiées correctement
• La config business n'est pas utilisée

Solutions :

1. Vérifier que tous les blips utilisent les rings standards : adopt, trial, assess, hold
2. Vérifier que radar-business/config-business.json contient bien les rings standards
3. Vérifier dans les logs Docker que les données ont été copiées :

   # Dans le conteneur
   find .techradar/data/radar -name "*.md" | wc -l
   # Doit retourner ~38 fichiers
   

4. Vérifier que config-business.json a été copié vers .techradar/data/config.json

Migration des rings :

# Migrer tous les blips vers les rings standards
cd radar-business/2025-01-15
find . -name "*.md" -exec sed -i 's/^ring: core$/ring: adopt/' {} \;
find . -name "*.md" -exec sed -i 's/^ring: strategic$/ring: assess/' {} \;
find . -name "*.md" -exec sed -i 's/^ring: support$/ring: adopt/' {} \;

Erreur "invalid ring"

Symptôme : Des erreurs "invalid ring" apparaissent dans les logs.

Cause : Les blips utilisent des rings qui ne sont pas définis dans la configuration.

Solution : Vérifier que tous les rings utilisés dans les blips sont bien définis dans config-business.json.

Page Equipe

Page /team affiche le radar au lieu des visualisations

Symptome : La page /team affiche le contenu du radar au lieu des visualisations equipe.

Causes possibles :

• Le script team-block-script.js n'est pas charge
• Le script patch_document.py n'a pas modifie _document.tsx
• Le script n'a pas pu remplacer le DOM

Solutions :

1. Verifier la console du navigateur (F12) pour les erreurs JavaScript
2. Verifier que le script team-block-script.js est inclus dans le HTML :

   curl -s http://localhost:3006/team/ | grep team-block-script
   

3. Rebuild avec --no-cache pour forcer l'execution des scripts Python

Verification :

# Dans le conteneur
ls -l .techradar/public/team-block-script.js
grep "team-block-script" .techradar/src/pages/_document.tsx

Page /team retourne 404

Symptome : La page /team n'est pas accessible ou retourne une erreur 404.

Causes possibles :

• La page Next.js team.tsx n'a pas ete creee
• Le serveur utilise --single qui redirige vers index.html

Solutions :

1. Verifier que le Dockerfile a bien cree .techradar/src/pages/team.tsx
2. Verifier que scripts/start-business.sh ne contient pas l'option --single
3. Verifier les logs du build Docker

Verification :

# Dans le conteneur
ls -l .techradar/src/pages/team.tsx
ls -l out/team/index.html

Donnees de visualisation manquantes ou erreur de chargement

Symptome : Les visualisations de la page equipe sont vides ou affichent une erreur.

Causes possibles :

• Le fichier team-visualization-data.json n'a pas ete genere
• Le fichier n'est pas accessible depuis le navigateur
• Erreur dans le chargement des bibliotheques (Cytoscape, ECharts)

Solutions :

1. Generer les donnees :

   node scripts/generate-team-visualization-data.js
   

2. Verifier que le fichier existe dans public/team-visualization-data.json
3. Verifier l'acces direct : http://localhost:3006/team-visualization-data.json
4. Verifier la console du navigateur pour les erreurs JavaScript
5. Verifier la connexion internet (les bibliotheques sont chargees depuis CDN)

Build Docker

Erreur "dockerfile parse error"

Symptôme : Erreur de syntaxe dans le Dockerfile.

Causes possibles :

• Commandes shell mal formatées dans les instructions RUN
• Variables mal échappées
• Heredocs mal fermés

Solution : Vérifier la syntaxe du Dockerfile, notamment :

• Les instructions RUN doivent être sur une seule ligne ou utiliser \ pour continuer
• Les heredocs doivent être correctement fermés
• Les variables shell doivent être échappées avec $$

Build utilise le cache alors que les fichiers ont changé

Symptôme : Les modifications ne sont pas prises en compte après un rebuild.

Cause : Docker utilise le cache des couches précédentes.

Solution : Rebuild avec --no-cache :

docker build --no-cache -f Dockerfile.business -t laplank-techradar-radar-business .

Dans Portainer, cocher l'option "No cache" lors du rebuild de la stack.

Script Python échoue avec exit code 2

Symptôme : Le script Python pour modifier Navigation.tsx échoue.

Causes possibles :

• Le fichier Navigation.tsx n'existe pas encore
• Problème de fin de ligne
• Erreur de syntaxe Python

Solutions :

1. Vérifier que le fichier existe avant d'exécuter le script
2. Vérifier les logs pour voir l'erreur exacte
3. Le script devrait afficher des messages de débogage

Déploiement

Les modifications ne sont pas visibles après déploiement

Symptôme : Après un déploiement, les changements ne sont pas visibles.

Causes possibles :

• Cache du navigateur
• Cache Docker
• Fichiers non copiés correctement

Solutions :

1. Vider le cache du navigateur (Ctrl+Shift+R ou Cmd+Shift+R)
2. Rebuild Docker avec --no-cache
3. Vérifier les logs pour confirmer que les fichiers ont été copiés

Erreur de permissions dans le conteneur

Symptôme : Erreurs de permissions lors de l'exécution.

Cause : Problème de permissions sur les fichiers ou répertoires.

Solution : Vérifier les permissions dans le Dockerfile et s'assurer que les fichiers sont accessibles.

Scripts

Script generate-team-visualization-data.js ne trouve pas les fichiers

Symptôme : Le script ne peut pas lire les fichiers de profils ou de technologies.

Cause : Chemins incorrects ou fichiers manquants.

Solution :

1. Vérifier que les fichiers existent :
   • docs/data/team/*.md
   • radar-business/2025-01-15/*.md
2. Exécuter le script depuis la racine du projet
3. Vérifier les chemins dans le script

Commandes utiles pour le débogage

Verifier les fichiers dans le conteneur

# Se connecter au conteneur
docker exec -it <container-name> /bin/sh

# Verifier les fichiers de la page equipe
ls -la .techradar/src/pages/team.tsx
ls -la .techradar/public/team-block-script.js
ls -la out/team-block-script.js
ls -la out/team-visualization-data.json

# Verifier les modifications
grep "team-block-script" .techradar/src/pages/_document.tsx
ls -la .techradar/src/components/Navigation/Navigation.tsx

# Compter les blips
find .techradar/data/radar -name "*.md" | wc -l

# Verifier la config
head -60 .techradar/data/config.json

Vérifier les logs

# Logs du conteneur
docker logs <container-name>

# Logs en temps réel
docker logs -f <container-name>

# Dernières lignes
docker logs --tail=100 <container-name>

Vérifier les rings dans les blips

# Lister tous les rings utilisés
cd radar-business/2025-01-15
grep -h "^ring:" *.md | sort | uniq -c

# Doit retourner uniquement : adopt, trial, assess, hold

Vérifier les liens dans Navigation.tsx

# Compter les liens Équipe
grep -c 'href="/team"' .techradar/src/components/Navigation/Navigation.tsx

# Voir le contexte autour du lien
grep -A 3 -B 3 'href="/team"' .techradar/src/components/Navigation/Navigation.tsx

Obtenir de l'aide

Si le problème persiste :

1. Vérifier les logs Docker complets
2. Vérifier la documentation dans docs/app/
3. Vérifier les issues sur le dépôt Git
4. Contacter l'équipe technique