1. Méthode Générale

Face à un problème, dans l’ordre :

  1. Dozzle (port 9999) — logs live du container concerné

  2. docker ps (SSH) — le container tourne-t-il ? Depuis quand ? Statut Restarting ?

  3. Beszel (port 8090) — RAM/CPU/disque saturés ?

  4. Grafana/Loki (port 3000) — historique des logs autour de l’incident

  5. La sortie Ansible elle-même — les playbooks échouent avec des messages explicites

# Connexion serveur (rappel : user "admin")
ssh -i ~/.ssh/serverAdminSSHKeypair.pem admin@18.158.207.98

2. Accès & Connexion

2.1. « Permission denied (publickey) » en SSH

# 1. Permissions de la clé
chmod 400 ~/.ssh/serverAdminSSHKeypair.pem

# 2. Bon utilisateur ? C'est "admin" (défini dans ansible/inventory/hosts.yml), PAS debian/root
ssh -i ~/.ssh/serverAdminSSHKeypair.pem admin@18.158.207.98

# 3. Toujours bloqué → vérifier la clé utilisée en mode verbeux
ssh -vvv -i ~/.ssh/serverAdminSSHKeypair.pem admin@18.158.207.98 2>&1 | grep -i "offering\|denied"

2.2. make ping échoue

# 1. Test SSH direct (ci-dessus). Si SSH marche mais pas Ansible :

# 2. Vérifier le vault (Ansible le charge même pour ping)
ls -l ~/.vault_sever_admin          # doit exister, chmod 600
cd sever-admin/ansible
ansible-vault view inventory/group_vars/all/vault.yml    # doit s'afficher en clair

# 3. Lancer depuis le bon dossier — ansible.cfg exige d'être dans ansible/
cd sever-admin && make ping         # le Makefile fait le cd ansible pour toi

2.3. « ERROR! Vault password did not match »

Le mot de passe dans ~/.vault_sever_admin est faux. Demander le bon au team lead, puis :

echo "LeBonMotDePasse" > ~/.vault_sever_admin
chmod 600 ~/.vault_sever_admin

Il existe DEUX fichiers vault password : ~/.vault_sever_admin (ton poste, utilisé par Makefile + ansible.cfg) et /opt/.vault_password (sur le serveur, utilisé par les crons — installé par make setup-cron depuis le .vault_password à la racine du repo).

3. Déploiement

3.1. « Application 'xxx' inconnue. Apps valides : …​ »

APP n’est pas dans la liste exacte des 19 cibles. Le message d’erreur Ansible liste lui-même les valeurs valides. Fautes fréquentes : clarajob-api → clarajob-front-api ; marketisia → marketisia-sa ; mongo → clarajob-mongo.

3.2. Le déploiement échoue à l’étape Git

# Cause 1 : la clé du serveur pour GitLab est absente/invalide
ssh admin@18.158.207.98
ls -l /home/admin/.ssh/id_ed25519       # doit exister
ssh -T git@gitlab.com -i /home/admin/.ssh/id_ed25519   # "Welcome, ..." attendu

# Cause 2 : modifications locales sur le serveur en conflit
# → le playbook fait git clean -fd + pull --force, mais si le .git est corrompu :
cd /home/admin/app/clarajob_sa && git status

3.3. docker login / pull d’image échoue

# Token registry expiré ou invalide. Vérifier :
cd sever-admin/ansible
ansible-vault view inventory/group_vars/all/vault.yml | grep registry
# → vault_gitlab_registry_token doit être un deploy token GitLab valide (scope read_registry)

# Si TAG fourni : le tag existe-t-il ?
# Vérifier dans GitLab → Container Registry du projet que l'image <tag> est publiée.

3.4. « Le container X n’est pas en cours d’exécution après le redémarrage »

Le rollback automatique a déjà relancé l’ancien état. Diagnostiquer pourquoi la nouvelle version crashe :

ssh admin@18.158.207.98
docker ps -a | grep <service>            # statut Exited ? Restarting ?
docker logs <container> --tail 100       # l'erreur est quasi toujours ici

# Causes classiques :
# - variable d'environnement manquante (fichier .env du repo applicatif incomplet)
# - DB inaccessible (container DB down ? mauvais hostname ?)
# - OOM : le container dépasse son mem_limit
docker inspect <container> | grep -i oomkilled
# - port déjà occupé sur l'hôte
sudo ss -tulpn | grep <port>

3.5. Build frontend échoue (clarajob-front-gui — sans TAG)

Le build tourne dans un container jetable sur le serveur (rôle deploy_frontend : node:lts-alpine + npm ci && npm run build par défaut). La sortie d’erreur est dans la sortie Ansible.

# Reproduire manuellement sur le serveur — clarajob-front-gui :
cd /home/admin/app/clarajob_sa
docker run --rm -v $PWD/clarajob-front-gui:/app -w /app node:lts-alpine \
  sh -c "npm ci && npm run build"

# Contournement : image pré-buildée par la CI
make deploy APP=clarajob-front-gui TAG=<tag-ci>
documentation n’a plus de build serveur : le site est pré-généré en local (gradle asciidoctor) et build/ est versionné. Si le site déployé est obsolète, vérifier que le build a bien été régénéré et committé avant le make deploy.

3.6. Traefik down → TOUS les sites inaccessibles

ssh admin@18.158.207.98
docker ps | grep traefik                 # tourne ?
docker logs traefik-service --tail 100   # erreurs de certificat/config ?

# Relance :
cd /home/admin/app/main-server-proxy && docker compose up -d traefik-service
# ou depuis ton poste :
make deploy APP=traefik

4. Bases de Données

4.1. PostgreSQL ne répond pas

ssh admin@18.158.207.98
docker ps | grep -E "clarajob-ddl|marketisia-ddl|auth_server_db"
docker exec clarajob-ddl pg_isready       # "accepting connections" attendu
docker logs clarajob-ddl --tail 50

# Redémarrage propre via Ansible (avec backup pre-deploy automatique) :
make deploy APP=clarajob-ddl

4.2. MongoDB ne répond pas

docker exec clarajob-mongo mongosh --quiet --eval "db.adminCommand('ping')"
# { ok: 1 } attendu
docker logs clarajob-mongo --tail 50
make deploy APP=clarajob-mongo            # restart via Ansible

4.3. « database is being accessed by other users » pendant un restore

L’API tient des connexions ouvertes. Arrêter l’API, restaurer, relancer :

ssh admin@18.158.207.98 "cd /home/admin/app/clarajob_sa && docker compose stop clarajob-front-api"
make restore APP=clarajob-ddl DUMP=<fichier.sql>
make deploy APP=clarajob-front-api

4.4. « Le dump …​ est vide ou n’a pas été créé » (backup)

# Credentials faux dans le vault, ou base inexistante :
cd sever-admin/ansible
ansible-vault view inventory/group_vars/all/vault.yml | grep clarajob_ddl
# Tester à la main avec ces credentials :
ssh admin@18.158.207.98
docker exec -e PGPASSWORD=<pass> clarajob-ddl psql -U <user> -d <db> -c "SELECT 1"

4.5. « Le fichier dump '…​' est introuvable » (restore)

# DUMP = nom de fichier exact (pas un chemin), présent dans db-config/dump/<service>/ :
ssh admin@18.158.207.98 \
  "ls -lht /home/admin/app/sever-admin/db-config/dump/clarajob-ddl/ | head"
# Copier-coller le nom exact dans make restore ... DUMP=<nom>

5. Backups Automatiques (Cron)

5.1. Vérifier que les crons tournent

ssh admin@18.158.207.98
sudo crontab -l
# Attendu : backup-marketisia-sa-daily (3h), backup-clarajob-ddl-daily (4h),
#           backup-clarajob-mongo-daily (5h)

tail -50 /var/log/ansible-backup.log      # dernières exécutions

# Dumps récents présents ?
ls -lht /home/admin/app/sever-admin/db-config/dump/clarajob-ddl/ | head -3

5.2. Cron présent mais aucun dump produit

# 1. Le vault serveur existe ?
sudo ls -l /opt/.vault_password           # sinon : relancer make setup-cron

# 2. Ansible installé sur le serveur ?
ansible --version

# 3. Tester le playbook manuellement SUR le serveur :
cd /home/admin/app/sever-admin/ansible
sudo ansible-playbook playbooks/backup.yml -e target_app=clarajob-ddl \
  --vault-password-file /opt/.vault_password

6. Système

6.1. Disque plein

df -h /
# Les 4 gros consommateurs habituels :
du -sh /home/admin/app/sever-admin/db-config/dump/*     # dumps DB (pas de purge auto !)
du -sh /home/admin/app/clarajob_sa/backups/minio/       # backups MinIO
docker system df                                        # images/volumes Docker
sudo sh -c 'du -sh /var/lib/docker/containers/*/*-json.log | sort -rh | head'  # logs containers

# Nettoyage :
# 1. Vieux dumps (garder les récents !)
find /home/admin/app/sever-admin/db-config/dump/ -name "*.sql" -mtime +30 -delete
# 2. Images Docker orphelines
docker image prune -a
# 3. Log d'un container devenu énorme (le glob DOIT s'étendre sous root, pas admin) :
sudo sh -c 'truncate -s 0 /var/lib/docker/containers/<id>/<id>-json.log'
# ⚠️ JAMAIS "docker volume prune" sans vérifier — risque de perte de données

Rotation des logs Docker (en place depuis juillet 2026) : /etc/docker/daemon.json plafonne chaque container à 3 fichiers de 50 Mo (max-size: 50m, max-file: 3).

Incident du 2026-07-26 : disque 100% plein (logs clarajob-front-api 8,2 Go
clarajob-mongo 3,3 Go + 83 volumes orphelins 31 Go) → crash de clarajob-mongo et échec de tout déploiement Ansible (« No usable temporary directory found »).

⚠️ La rotation ne s’applique qu’aux containers créés après la config : un container existant garde des logs illimités jusqu’à sa recréation (prochain deploy qui le recrée). En cas de doute : docker inspect <container> --format '{{.HostConfig.LogConfig}}'.

6.2. RAM saturée / OOM

# Beszel (port 8090) montre l'historique. En direct :
docker stats --no-stream | sort -k7 -h

# Qui a été tué par l'OOM-killer ?
docker ps -a --format 'table {{.Names}}\t{{.Status}}' | grep -i exited
docker inspect <container> | grep -i oomkilled

# Rappel : chaque service a un mem_limit dans son compose (40m à 1g).
# Rundeck seul consomme ~1 Go — l'arrêter si non utilisé :
cd /home/admin/app/sever-admin && docker compose stop rundeck

6.3. Un container en « Restarting » permanent

docker ps | grep -i restarting
docker logs <container> --tail 50         # boucle de crash : la cause est là
# Souvent : dépendance pas prête (DB), variable d'env manquante, OOM

7. Récupération Complète (Disaster Recovery)

Si le serveur est perdu, la reconstruction s’appuie sur : les repos Git (tout le code
compose), le vault (secrets), et les dumps (données).

# 1. Nouveau serveur Debian Lightsail : installer docker + docker compose + git
# 2. Créer le réseau partagé
docker network create proxy_server_network

# 3. Cloner les 5 repos dans /home/admin/app/
#    (sever-admin, clarajob_sa, marketisia, auth-server, main-server-proxy)
#    + installer la clé GitLab /home/admin/.ssh/id_ed25519

# 4. Depuis ton poste : mettre à jour l'IP dans ansible/inventory/hosts.yml

# 5. Déployer les stacks
make deploy APP=traefik
make deploy APP=clarajob-sa
make deploy APP=marketisia-sa
make deploy APP=auth-server-db && make deploy APP=keycloak
ssh admin@<ip> "cd /home/admin/app/sever-admin && docker compose up -d"

# 6. Restaurer les données (les dumps doivent avoir été copiés hors serveur au préalable —
#    les remettre dans db-config/dump/<service>/ sur le nouveau serveur)
make restore APP=clarajob-ddl   DUMP=<dernier.sql>
make restore APP=clarajob-mongo DUMP=<dernier.archive>
make restore APP=marketisia-sa  DUMP=<dernier.sql>
make restore APP=auth-server-db DUMP=<dernier.sql>
make restore APP=minio-service  DUMP=latest

# 7. Réinstaller les crons
make setup-cron

Ce plan suppose que les dumps ont été copiés hors du serveur régulièrement — ce qui n’est pas automatisé aujourd’hui. Sans copie externe, les dumps disparaissent avec le serveur. Voir la recommandation dans Backup & Restore.

8. Aide-Mémoire

make ping                                  # test connexion
make backup APP=all                        # tout sauvegarder avant une manip risquée
make deploy APP=<service>                  # redéployer/redémarrer un service (19 cibles)
make restore APP=<db> DUMP=<fichier>       # restaurer

# Sur le serveur :
docker ps                                  # état des containers
docker logs <container> --tail 100         # logs
tail -50 /var/log/ansible-backup.log       # logs backups cron
df -h / && docker stats --no-stream        # disque + RAM/CPU

# UIs : Dozzle 9999 · Beszel 8090 · Grafana 3000 · Kafka UI 8091 ·
#       RabbitMQ 15672 · Adminer 9093 · pgAdmin 5050 · Semaphore 3001