Pièges et dépannage
En bref
Niveau : intermédiaire
Durée : 20 minutes de lecture
Prérequis : avoir lu les pages de rôles
Niveau de test : reconstitué
Dépanner, c'est quoi ?
Une application qui ne répond pas peut tomber en panne à plusieurs endroits : le DNS, le certificat, Traefik, Authentik, l'application elle-même. Chercher au hasard fait perdre du temps. La méthode la plus sûre consiste à remonter le chemin d'une requête, étape par étape, et à s'arrêter à la première qui échoue.
| Étape | Question | Page de référence |
|---|---|---|
| 1. DNS | Le nom pointe-t-il vers la bonne adresse ? | Traefik |
| 2. Pare-feu | Les ports 80 et 443 sont-ils ouverts et joignables ? | Socle |
| 3. Traefik | Le routeur existe-t-il et le certificat est-il délivré ? | Traefik |
| 4. Application | Le conteneur tourne-t-il et répond-il ? | Page de l'application |
| 5. SSO | La connexion par Authentik aboutit-elle ? | Authentik |
| 6. Blocage | L'adresse du visiteur est-elle bloquée ? | Fail2ban |
DNS → pare-feu → Traefik → application → SSO → blocage éventuel
Les commandes de diagnostic
# 1. DNS : l'adresse retournée doit être l'adresse publique de la VM.
dig +short cloud.penhoat.example
# 2. Pare-feu : règles de la VM et chaîne des blocages.
sudo ufw status verbose
sudo iptables -L DOCKER-USER -n
# 3. Traefik : journal de démarrage, puis requêtes récentes.
docker logs --tail 50 alpha_traefik
sudo tail -n 20 /var/log/traefik/access.log
# 4. Application : conteneurs, puis journal d'un conteneur précis.
docker ps --format '{{.Names}}\t{{.Status}}'
docker logs --tail 50 alpha_nextcloud
# 5. SSO : l'API d'Authentik répond.
curl -sSk --resolve sso.penhoat.example:443:127.0.0.1 https://sso.penhoat.example/-/health/live/
# 6. Blocage : adresses bloquées par jail.
sudo fail2ban-client status nebuleuse-traefik
Symptômes courants
| Symptôme | Cause probable | Vérification et correction |
|---|---|---|
| Le navigateur affiche une erreur de certificat | Certificat non délivré, ou mode staging actif |
traefik_acme_staging doit valoir false ; examiner le journal de Traefik pour l'erreur ACME |
| Erreur 404 de Traefik | Le routeur n'existe pas | Labels traefik.enable et Host(...) absents ou erronés dans le fichier Compose |
| Erreur 502 ou 504 | Traefik n'atteint pas le conteneur | Mauvais port dans loadbalancer.server.port, conteneur hors du réseau proxy, label traefik.docker.network manquant |
| Boucle de connexion sur le SSO | Mauvais flux sur le provider | Le provider doit utiliser le flux d'autorisation (page Authentik) |
| « Redirect URI invalide » | Adresse de retour différente | Comparer caractère pour caractère l'adresse du provider et celle de l'application |
| « Accès refusé » après connexion | Pas de règle d'accès liée à l'application | Lier la règle nebuleuse-allow-all à l'application |
| L'application ne joint pas le SSO | Détour par l'adresse publique | Alias réseau de Traefik pour sso.<domaine> |
| Visiteur légitime bloqué | Seuil trop bas, ou adresse partagée | fail2ban-client set <jail> unbanip <adresse>, puis relever le seuil ou ajouter à ignoreip |
Le déploiement échoue sur une variable vault_... |
Secret absent du Vault | Contrôle des secrets en début de site.yml |
| SSH refusé après le socle | Pare-feu ou ListenAddress |
Se connecter par la console de l'hébergeur et vérifier sshd -T |
| Le disque se remplit | Journaux ou bibliothèque Immich | docker system df ; du -sh /opt/nebuleuse/* ; vérifier la rotation du journal Traefik |
Où sont les journaux ?
| Élément | Emplacement |
|---|---|
| Journal d'accès de Traefik | /var/log/traefik/access.log |
| Traefik, applications, Authentik | docker logs <conteneur> |
| Vaultwarden | /opt/nebuleuse/vaultwarden/data/vaultwarden.log |
| Fail2ban | /var/log/fail2ban.log |
| Ansible | Sortie du terminal ; pour garder une trace : -vv, ou une redirection vers un fichier |
Si le déploiement échoue en cours de route
Un déploiement qui s'arrête au milieu laisse la VM dans un état intermédiaire, mais rejouable : les rôles sont idempotents.
- Lire le message de la première tâche en erreur : les suivantes en découlent souvent.
- Corriger la cause (variable, secret, DNS, connectivité).
- Rejouer le playbook sur ce client, avec la même commande.
- Si l'erreur persiste dans un rôle précis, le rejouer seul avec
--tagset-vvpour afficher le détail des appels.
# Rejouer un seul rôle avec le détail de chaque tâche.
ansible-playbook site.yml --limit client-alpha --tags sso -vv
Remettre une application à zéro
Cette opération supprime les données de l'application : elle n'est à faire que sur une VM d'essai, ou après une sauvegarde.
# Sur la VM : arrêter l'application et supprimer ses conteneurs.
cd /opt/nebuleuse/nextcloud && docker compose down
# Supprimer ses données (IRRÉVERSIBLE).
sudo rm -rf /opt/nebuleuse/nextcloud/html /opt/nebuleuse/nextcloud/db-data
# Depuis le serveur Ansible : redéployer.
ansible-playbook site.yml --limit client-alpha --tags nextcloud
Les variables d'installation (compte administrateur, base de données) ne sont lues qu'au premier démarrage. Pour les changer, il faut soit passer par l'outil du service (occ, interface d'administration), soit repartir de zéro comme ci-dessus.
Pour aller plus loin
- Sauvegardes : aucun rôle de sauvegarde n'est décrit ici. Il faudrait sauvegarder les dossiers
/opt/nebuleuse/<application>de chaque client, ainsi que le dépôt Git et le mot de passe du Vault du serveur Ansible. - Supervision : la page de la base de connaissance sur la supervision (à écrire) permettrait de surveiller les certificats, l'espace disque et les conteneurs de chaque VM.
- Mises à jour : les versions d'images sont figées dans les variables des rôles. Un rythme de mise à jour (mensuel, par exemple) et une procédure de retour arrière restent à définir.
Page suivante : Fiche Atelier Penhoat.