====== 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 ====

<code bash>
# 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
</code>

==== Script de diagnostic automatique ====

<code bash>
#!/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 "========================================="
</code>

---

===== Problèmes courants =====

==== Service inaccessible (404 ou timeout) ====

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

**Diagnostic :**

<code bash>
# 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
</code>

**Solutions :**

<code bash>
# 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
</code>

---

==== Certificat SSL invalide ou expiré ====

**Symptôme :** Erreur de certificat dans le navigateur

**Diagnostic :**

<code bash>
# 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
</code>

**Solutions :**

<code bash>
# 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
</code>

---

==== Container en boucle de redémarrage (Restarting) ====

**Symptôme :** Container affiche "Restarting (X)" dans `docker ps`

**Diagnostic :**

<code bash>
# Voir les logs d'erreur
docker logs [container] --tail 100

# Voir les derniers crashs
docker events --since 1h | grep [container]
</code>

**Causes fréquentes et solutions :**

**Cause 1 : Problème de permissions**

<code bash>
# 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
</code>

**Cause 2 : Configuration incorrecte**

<code bash>
# 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
</code>

**Cause 3 : Base de données corrompue**

<code bash>
# 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
</code>

---

==== DNS ne fonctionne pas ====

**Symptôme :** `nslookup` ne retourne pas 192.168.1.200

**Diagnostic :**

<code bash>
# Tester DNS
nslookup [service].cotting.fr 192.168.1.200

# Vérifier AdGuard
docker ps | grep adguard
docker logs adguard --tail 50
</code>

**Solutions :**

<code bash>
# 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
</code>

---

==== Espace disque plein ====

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

**Diagnostic :**

<code bash>
# 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
</code>

**Solutions :**

<code bash>
# 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 {} \;
</code>

---

==== Base de données ne démarre pas ====

**Symptôme :** MariaDB ou PostgreSQL en erreur

**Diagnostic pour MariaDB (Généalogie) :**

<code bash>
# 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
</code>

**Solutions MariaDB :**

<code bash>
# 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]]
</code>

**Diagnostic pour PostgreSQL (Paperless) :**

<code bash>
# Logs
docker logs paperless-db --tail 100
</code>

**Solutions PostgreSQL :**

<code bash>
# 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]]
</code>

---

==== Traefik ne détecte pas un service ====

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

**Diagnostic :**

<code bash>
# 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]
</code>

**Solutions :**

<code bash>
# 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]]
</code>

---

==== Backup échoue ====

**Symptôme :** Script de backup retourne une erreur

**Diagnostic :**

<code bash>
# Logs du backup
tail -100 /var/log/backup-all.log

# Test manuel
sudo /opt/scripts/backup-[service].sh
</code>

**Causes fréquentes :**

<code bash>
# 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
</code>

---

===== Problèmes réseau =====

==== Pas d'accès Internet depuis les containers ====

**Diagnostic :**

<code bash>
# 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
</code>

**Solutions :**

<code bash>
# 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
</code>

---

===== Procédures d'urgence =====

==== Tout redémarrer (urgence) ====

<code bash>
# ⚠️ À 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
</code>

==== Restauration complète depuis backup ====

Voir [[infrastructure:backups:restore|Guide de restauration complet]]

==== Mode maintenance ====

<code bash>
# 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]"
</code>

---

===== Logs et monitoring =====

==== Accéder aux logs ====

<code bash>
# 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
</code>

==== Exporter les logs pour analyse ====

<code bash>
# 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)/
</code>

---

===== 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 :** [[infrastructure:start|Wiki infrastructure]]
  * **Backups :** [[infrastructure:backups|Gestion backups]]
  * **Procédures :** [[infrastructure:procedures|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 ! 📝

----

[[infrastructure:start|← Retour accueil]]