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 Équipe

Page /team retourne 404

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

Causes possibles :

• Le fichier team.html n'est pas dans out/
• La page Next.js team.tsx n'a pas été créée
• Le fichier n'a pas été copié dans .techradar/public/

Solutions :

1. Vérifier que public/team.html existe
2. Vérifier que le Dockerfile a bien créé .techradar/src/pages/team.tsx
3. Vérifier que team.html a été copié dans .techradar/public/ puis dans out/
4. Vérifier les logs du script start-business.sh qui doit copier les fichiers manquants

Vérification :

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

Données de visualisation manquantes

Symptôme : Les visualisations de la page équipe sont vides.

Cause : Le fichier team-visualization-data.json n'a pas été généré ou n'est pas accessible.

Solution :

1. Générer les données :

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

2. Vérifier que le fichier existe dans public/team-visualization-data.json
3. Vérifier que le fichier a été copié dans out/ lors du build

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

Vérifier les fichiers dans le conteneur

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

# Vérifier les fichiers
ls -la .techradar/src/pages/team.tsx
ls -la .techradar/src/components/Navigation/Navigation.tsx
ls -la .techradar/public/team.html
ls -la out/team.html

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

# Vérifier 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