Guide de Dépannage

<WRAP center round tip 60%> 💡 Conseil : Avant de paniquer, vérifiez les bases (réseau, DNS, logs) </WRAP>

Diagnostic rapide

Commandes de diagnostic général

# 1. Vérifier tous les services
docker ps --format "table {{.Names}}\t{{.Status}}"
 
# 2. Vérifier les ressources système
docker stats --no-stream
 
# 3. Espace disque
df -h
 
# 4. Mémoire
free -h
 
# 5. Charge système
uptime

Script de diagnostic automatique

#!/bin/bash
# /opt/scripts/diagnose.sh
 
echo "========================================="
echo "🔍 DIAGNOSTIC INFRASTRUCTURE"
echo "========================================="
 
echo ""
echo "📊 État des services:"
docker ps --format "table {{.Names}}\t{{.Status}}" | grep -E "genealogie|paperless|vaultwarden|traefik|adguard"
 
echo ""
echo "💾 Espace disque:"
df -h | grep -E "/$|/opt"
 
echo ""
echo "🧠 Mémoire:"
free -h | grep -E "Mem|Swap"
 
echo ""
echo "🌡️  Charge système:"
uptime
 
echo ""
echo "🔌 Réseau:"
ping -c 3 8.8.8.8 >/dev/null 2>&1 && echo "✅ Internet OK" || echo "❌ Pas d'internet"
ping -c 3 192.168.1.254 >/dev/null 2>&1 && echo "✅ Passerelle OK" || echo "❌ Problème passerelle"
 
echo ""
echo "🔒 Certificats SSL (expiration):"
for domain in genealogie paperless vaultwarden wiki; do
    EXPIRE=$(echo | openssl s_client -servername $domain.cotting.fr -connect 192.168.1.200:443 2>/dev/null | openssl x509 -noout -dates 2>/dev/null | grep notAfter | cut -d= -f2)
    echo "  $domain.cotting.fr: $EXPIRE"
done
 
echo "========================================="

—

Problèmes courants

Service inaccessible (404 ou timeout)

Symptôme : Page “404 Not Found” ou timeout lors de l'accès à un service

Diagnostic :

# 1. Vérifier que le container tourne
docker ps | grep [nom-service]
 
# Si "Restarting" ou absent :
docker logs [container] --tail 50
 
# 2. Vérifier le DNS
nslookup [service].cotting.fr 192.168.1.200
# Doit retourner : 192.168.1.200
 
# 3. Vérifier Traefik Dashboard
# http://192.168.1.200:8080
# HTTP → Routers → Chercher le service
# Doit être en VERT
 
# 4. Tester depuis Traefik
docker exec traefik ping -c 3 [container-name]
docker exec traefik wget -O- http://[container]:80 | head

Solutions :

# Solution 1 : Redémarrer le service
cd /opt/stacks/[service]
docker compose restart
 
# Solution 2 : Redémarrer Traefik
docker restart traefik
 
# Solution 3 : Vérifier les labels Docker
docker inspect [container] | grep traefik
 
# Solution 4 : Recréer le container
cd /opt/stacks/[service]
docker compose down
docker compose up -d

—

Certificat SSL invalide ou expiré

Symptôme : Erreur de certificat dans le navigateur

Diagnostic :

# Vérifier les certificats
sudo cat /opt/stacks/traefik/letsencrypt/acme.json | jq '.le.Certificates[] | .domain.main'
 
# Vérifier l'expiration
echo | openssl s_client -servername [service].cotting.fr -connect 192.168.1.200:443 2>/dev/null | openssl x509 -noout -dates

Solutions :

# Solution 1 : Forcer le renouvellement
docker restart traefik
 
# Solution 2 : Supprimer le certificat et le régénérer
docker stop traefik
sudo cp /opt/stacks/traefik/letsencrypt/acme.json /opt/backups/acme.json.backup
sudo nano /opt/stacks/traefik/letsencrypt/acme.json
# Supprimer l'entrée du domaine concerné dans le JSON
docker start traefik
 
# Solution 3 : Vérifier les logs Traefik
docker logs traefik | grep -i certificate
docker logs traefik | grep -i acme

—

Container en boucle de redémarrage (Restarting)

Symptôme : Container affiche “Restarting (X)” dans `docker ps`

Diagnostic :

# Voir les logs d'erreur
docker logs [container] --tail 100
 
# Voir les derniers crashs
docker events --since 1h | grep [container]

Causes fréquentes et solutions :

Cause 1 : Problème de permissions

# Exemple pour Paperless
sudo chown -R 999:999 /opt/stacks/paperless/database
sudo chown -R 1000:1000 /opt/stacks/paperless/data
 
# Exemple pour Vaultwarden
sudo chown -R 1000:1000 /opt/stacks/vaultwarden/data

Cause 2 : Configuration incorrecte

# Vérifier le .env
cat /opt/stacks/[service]/.env
 
# Vérifier le docker-compose.yml
cat /opt/stacks/[service]/docker-compose.yml
 
# Tester la syntaxe YAML
docker compose config

Cause 3 : Base de données corrompue

# Voir [[infrastructure:backups|restauration depuis backup]]
 
# Ou réinitialiser (⚠️ PERTE DE DONNÉES)
cd /opt/stacks/[service]
docker compose down
sudo rm -rf database
docker compose up -d

—

DNS ne fonctionne pas

Symptôme : `nslookup` ne retourne pas 192.168.1.200

Diagnostic :

# Tester DNS
nslookup [service].cotting.fr 192.168.1.200
 
# Vérifier AdGuard
docker ps | grep adguard
docker logs adguard --tail 50

Solutions :

# Solution 1 : Vérifier DNS Rewrites dans AdGuard
# https://adguard.cotting.fr
# Filters → DNS rewrites
# Vérifier que [service].cotting.fr → 192.168.1.200 existe
 
# Solution 2 : Redémarrer AdGuard
docker restart adguard
sleep 10
 
# Solution 3 : Vider le cache DNS du client
# Linux
sudo systemd-resolve --flush-caches
# Windows
ipconfig /flushdns
# Mac
sudo dscacheutil -flushcache

—

Espace disque plein

Symptôme : Services ne démarrent pas, erreurs d'écriture

Diagnostic :

# Vérifier l'espace
df -h
 
# Trouver les gros fichiers
sudo du -sh /opt/stacks/* | sort -h
sudo du -sh /opt/backups/* | sort -h
sudo du -sh /var/lib/docker/* | sort -h

Solutions :

# Solution 1 : Nettoyer Docker
docker system prune -a --volumes
# ⚠️ Attention : supprime images et volumes non utilisés
 
# Solution 2 : Nettoyer les backups anciens
find /opt/backups -type d -name "20*" -mtime +60 -exec rm -rf {} \;
 
# Solution 3 : Nettoyer les logs
sudo journalctl --vacuum-time=7d
docker logs --since 24h [container] > /dev/null  # Rotation
 
# Solution 4 : Identifier les gros fichiers
sudo find /opt -type f -size +100M -exec ls -lh {} \;

—

Base de données ne démarre pas

Symptôme : MariaDB ou PostgreSQL en erreur

Diagnostic pour MariaDB (Généalogie) :

# Logs
docker logs genealogie-db --tail 100
 
# Erreurs courantes :
# - "Permission denied" → Problème de permissions
# - "Table doesn't exist" → Base corrompue
# - "Can't connect" → Problème réseau

Solutions MariaDB :

# Solution 1 : Permissions
sudo chown -R 999:999 /opt/stacks/genealogie/database
sudo chmod -R 700 /opt/stacks/genealogie/database
 
# Solution 2 : Réparer les tables
docker exec genealogie-db mariadb-check -u root -p --auto-repair --all-databases
 
# Solution 3 : Restaurer depuis backup
# Voir [[infrastructure:backups:restore]]

Diagnostic pour PostgreSQL (Paperless) :

# Logs
docker logs paperless-db --tail 100

Solutions PostgreSQL :

# Solution 1 : Permissions
sudo chown -R 999:999 /opt/stacks/paperless/database
sudo chmod -R 700 /opt/stacks/paperless/database
 
# Solution 2 : Restaurer depuis backup
# Voir [[infrastructure:backups:restore]]

—

Traefik ne détecte pas un service

Symptôme : Router n'apparaît pas dans le Dashboard Traefik

Diagnostic :

# Vérifier les labels
docker inspect [container] | grep "traefik"
 
# Vérifier le réseau
docker inspect [container] | grep -A 5 "Networks"
# Doit afficher "dashboard_web"
 
# Vérifier les logs Traefik
docker logs traefik | grep -i [service]

Solutions :

# Solution 1 : Vérifier que le container est sur dashboard_web
docker network connect dashboard_web [container]
 
# Solution 2 : Redémarrer Traefik
docker restart traefik
 
# Solution 3 : Recréer le container
cd /opt/stacks/[service]
docker compose down
docker compose up -d
docker restart traefik
 
# Solution 4 : Créer un fichier de config statique
sudo nano /opt/stacks/traefik/dynamic/[service].yml
# Voir [[infrastructure:procedures:nouveau-service]]

—

Backup échoue

Symptôme : Script de backup retourne une erreur

Diagnostic :

# Logs du backup
tail -100 /var/log/backup-all.log
 
# Test manuel
sudo /opt/scripts/backup-[service].sh

Causes fréquentes :

# Cause 1 : Espace disque plein
df -h /opt/backups
 
# Cause 2 : Permissions
ls -la /opt/backups/
sudo chown -R root:root /opt/scripts/
sudo chmod +x /opt/scripts/*.sh
 
# Cause 3 : Base de données inaccessible
docker ps | grep -E "db|mariadb|postgres"
 
# Cause 4 : Fichier .env manquant/corrompu
cat /opt/stacks/[service]/.env

—

Problèmes réseau

Pas d'accès Internet depuis les containers

Diagnostic :

# Test depuis un container
docker exec genealogie-app ping -c 3 8.8.8.8
 
# Vérifier la config réseau Docker
sudo cat /etc/docker/daemon.json
 
# Vérifier le DNS Docker
docker run --rm busybox nslookup google.com

Solutions :

# Solution 1 : Redémarrer Docker
sudo systemctl restart docker
 
# Solution 2 : Configurer le DNS Docker
sudo nano /etc/docker/daemon.json
```
{
  "dns": ["8.8.8.8", "8.8.4.4"]
}
```
sudo systemctl restart docker
 
# Solution 3 : Vérifier le firewall
sudo ufw status
sudo iptables -L

—

Procédures d'urgence

Tout redémarrer (urgence)

# ⚠️ À utiliser en dernier recours
 
# 1. Redémarrer tous les services
cd /opt/stacks/genealogie && docker compose restart
cd /opt/stacks/paperless && docker compose restart
cd /opt/stacks/vaultwarden && docker compose restart
docker restart traefik adguard heimdall dokuwiki
 
# 2. Ou redémarrer Docker complètement
sudo systemctl restart docker
 
# 3. Ou redémarrer le serveur
sudo reboot

Restauration complète depuis backup

Voir Guide de restauration complet

Mode maintenance

# Arrêter tous les services sauf infrastructure
cd /opt/stacks/genealogie && docker compose stop
cd /opt/stacks/paperless && docker compose stop
cd /opt/stacks/vaultwarden && docker compose stop
 
# Garder actifs : Traefik, AdGuard, Heimdall, DokuWiki
 
# Message dans Heimdall :
# "Infrastructure en maintenance - Retour prévu : [date/heure]"

—

Logs et monitoring

Accéder aux logs

# Logs temps réel
docker logs -f [container]
 
# Dernières lignes
docker logs --tail 100 [container]
 
# Logs avec timestamps
docker logs -t [container]
 
# Logs depuis une date
docker logs --since "2026-02-01T00:00:00" [container]
 
# Logs système
sudo journalctl -u docker -f
sudo journalctl -u docker --since today

Exporter les logs pour analyse

# Créer un rapport de logs
mkdir -p /tmp/logs-export-$(date +%Y%m%d)
 
for container in genealogie-app paperless-app vaultwarden traefik adguard; do
    docker logs $container --tail 1000 > /tmp/logs-export-$(date +%Y%m%d)/$container.log 2>&1
done
 
# Compresser
tar -czf /opt/backups/logs-export-$(date +%Y%m%d).tar.gz /tmp/logs-export-$(date +%Y%m%d)/

—

Checklist de dépannage générale

Quand un problème survient, suivre cette checklist :

[ ] Identifier le problème : Quel service ? Quel symptôme ?
[ ] Consulter les logs : `docker logs [container]`
[ ] Vérifier l'état : `docker ps | grep [service]`
[ ] Tester le réseau : DNS, ping, curl
[ ] Vérifier Traefik : Dashboard, routers, services
[ ] Essayer un redémarrage : `docker compose restart`
[ ] Vérifier les ressources : Espace disque, mémoire
[ ] Consulter cette page : Problèmes connus
[ ] Restaurer depuis backup si nécessaire
[ ] Documenter la solution dans cette page !

—

Contacts et ressources

Admin : Olivier Cotting - olivier@cotting.fr
Documentation : Wiki infrastructure
Backups : Gestion backups
Procédures : Procédures

Ajouter un problème à cette page

Si vous rencontrez un nouveau problème et trouvez la solution :

Cliquez sur “Edit this page”
Ajoutez une nouvelle section avec :
- Symptôme : Description du problème
- Diagnostic : Comment identifier la cause
- Solution : Étapes de résolution
Sauvegardez

Merci de contribuer à cette documentation ! 📝

← Retour accueil

Table of Contents

Guide de Dépannage

Diagnostic rapide

Commandes de diagnostic général

Script de diagnostic automatique

Problèmes courants

Service inaccessible (404 ou timeout)

Certificat SSL invalide ou expiré

Container en boucle de redémarrage (Restarting)

DNS ne fonctionne pas

Espace disque plein

Base de données ne démarre pas

Traefik ne détecte pas un service

Backup échoue

Problèmes réseau

Pas d'accès Internet depuis les containers

Procédures d'urgence

Tout redémarrer (urgence)

Restauration complète depuis backup

Mode maintenance

Logs et monitoring

Accéder aux logs

Exporter les logs pour analyse

Checklist de dépannage générale

Contacts et ressources

Ajouter un problème à cette page