Skip to main content

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.

  1. Lire le message de la première tâche en erreur : les suivantes en découlent souvent.
  2. Corriger la cause (variable, secret, DNS, connectivité).
  3. Rejouer le playbook sur ce client, avec la même commande.
  4. Si l'erreur persiste dans un rôle précis, le rejouer seul avec --tags et -vv pour 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.

No comments to display

Back to top