1. Vue d’Ensemble

Le Makefile à la racine de sever-admin est le point d’entrée de toutes les opérations. Il ne fait qu’une chose : appeler les playbooks Ansible avec les bons paramètres.

Il existe exactement 6 commandes :

Commande Rôle

make help

Afficher l’aide et les usages

make ping

Tester la connexion SSH/Ansible au serveur

make backup APP=<app>

Backup d’une base de données (dump dans db-config/dump/)

make restore APP=<app> DUMP=<fichier>

Restaurer une base depuis un fichier dump

make deploy APP=<app> [TAG=x] [BRANCH=x]

Déployer une application ou un service

make setup-cron

Installer les crons de backup automatique sur le serveur

APP est obligatoire pour backup, restore et deploy — il n’y a pas de valeur par défaut. Toute autre commande (make status, make logs, make backup-all, etc.) n’existe pas dans ce projet.

2. Paramètres Globaux

Paramètre Valeurs Description

APP

voir listes ci-dessous

Application/service cible (obligatoire sauf ping/setup-cron/help)

ENV

remote (défaut) / local

remote → groupe Ansible production (serveur Lightsail)
local → groupe Ansible local (ta machine, ansible_connection: local)

TAG

ex: v1.2.0, abc1234

Tag d’image Docker à déployer depuis le GitLab Container Registry (deploy uniquement)

BRANCH

ex: develop, feature/x

Branche Git à puller (défaut : main — variable deploy_git_branch)

DUMP

nom de fichier

Fichier dump à restaurer (restore uniquement), situé dans db-config/dump/<service>/

Prérequis technique : le fichier ~/.vault_sever_admin (mot de passe Ansible Vault, chmod 600) doit exister — le Makefile passe systématiquement --vault-password-file $(HOME)/.vault_sever_admin.

3. make ping

Teste la connexion au serveur de production.

make ping
# Exécute : cd ansible && ansible production -m ping --vault-password-file ~/.vault_sever_admin
# Attendu : vps-main | SUCCESS => { "ping": "pong" }

4. make backup

Backup d’une base de données via ansible/playbooks/backup.yml.

Valeurs APP valides : clarajob-ddl | clarajob-mongo | marketisia-sa | auth-server-db | all

make backup APP=clarajob-ddl        # PostgreSQL ClaraJob
make backup APP=clarajob-mongo      # MongoDB ClaraJob
make backup APP=marketisia-sa       # PostgreSQL Marketisia/PredictX (container marketisia-ddl)
make backup APP=auth-server-db      # PostgreSQL Keycloak
make backup APP=all                 # Les 4 bases d'un coup
make backup APP=clarajob-ddl ENV=local   # Sur ta machine locale

Ce que fait le rôle backup :

  1. Valide db_service, db_name, db_user, db_pass (depuis vars.yml + vault.yml)

  2. Crée db-config/dump/<service>/ et db-config/dump_description/<service>/

  3. Vérifie que le container DB tourne (docker inspect)

  4. Lance le dump dans le container :

    • PostgreSQL : pg_dump --clean --if-exists → fichier .sql

    • MongoDB : mongodump --archive → fichier .archive

    • MySQL (supporté par le rôle) : mysqldump --add-drop-table --routines --triggers

  5. Vérifie que le dump existe et n’est pas vide (sinon échec)

  6. Écrit un fichier de description horodaté

Nommage des fichiers produits :

db-config/dump/<db_service>/<db_service>-YYYY-MM-DD_HHMMSS.sql       # PostgreSQL / MySQL
db-config/dump/<db_service>/<db_service>-YYYY-MM-DD_HHMMSS.archive   # MongoDB

Exemples réels :
db-config/dump/clarajob-ddl/clarajob-ddl-2026-07-26_040000.sql
db-config/dump/clarajob-mongo/clarajob-mongo-2026-07-26_050000.archive
db-config/dump/marketisia-ddl/marketisia-ddl-2026-07-26_030000.sql

Les dumps ne sont pas compressés (pas de .gz) et il n’y a pas de purge automatique dans le rôle backup — le nettoyage des vieux dumps est manuel.

5. make restore

Restaure une base depuis un dump via ansible/playbooks/restore.yml. APP et DUMP sont obligatoires.

Valeurs APP valides : clarajob-ddl | clarajob-mongo | marketisia-sa | auth-server-db | minio-service

make restore APP=clarajob-ddl DUMP=clarajob-ddl-2026-07-26_040000.sql
make restore APP=clarajob-mongo DUMP=clarajob-mongo-2026-07-26_050000.archive
make restore APP=marketisia-sa DUMP=marketisia-ddl-2026-07-26_030000.sql
make restore APP=auth-server-db DUMP=auth_server_db-2026-07-26_060000.sql

# MinIO (object storage) — cas particulier :
make restore APP=minio-service DUMP=latest                       # dernier backup mc mirror
make restore APP=minio-service DUMP=/chemin/vers/backup/2026-04-05_0600

Ce que fait le rôle restore (bases de données) :

  1. Vérifie que le container DB tourne

  2. Cherche le dump dans db-config/dump/<db_service>/<DUMP> — échec explicite s’il est introuvable

  3. Restaure dans le container :

    • PostgreSQL : psql -U <user> -d <db> < dump (le dump contient --clean --if-exists, donc drop/recreate des objets)

    • MongoDB : mongorestore --drop --archive < dump (--drop écrase les collections existantes)

    • MySQL : mysql <db> < dump

Ce que fait le rôle restore_minio :

  1. Si DUMP=latest : sélectionne le répertoire de backup le plus récent dans clarajob_sa/backups/minio/

  2. Arrête minio-service

  3. Restaure via docker run minio/mc : mc mirror /backups/ /data/ vers le volume clarajob_sa_minio_data

  4. Redémarre minio-service, vérifie qu’il tourne, rollback sinon

6. make deploy

Déploie une application via ansible/playbooks/deploy.yml.

Les 19 valeurs APP valides (liste exacte du assert du playbook) :

APP Ce qui se passe Rôle Ansible utilisé

clarajob-sa

git pull du repo clarajob_sa + pull images GitLab (clarajob-ddl, clarajob-front-api, clarajob-front-gui, clarajob-embedding) + docker compose up -d tout le stack + backups pre-deploy auto (DDL + Mongo)

bloc inline (avec rollback)

clarajob-ddl

git pull + restart du container PostgreSQL + backup pre-deploy auto

deploy

clarajob-mongo

restart du service MongoDB (pas de build) + backup pre-deploy auto

deploy

clarajob-front-api

restart de l’API Spring Boot (image GitLab)

deploy

clarajob-front-gui

git pull + build npm dans un container node (node:lts-alpine, npm ci && npm run build) OU pull image si TAG fourni + restart Nginx

deploy_frontend

clarajob-embedding

restart du service embedding FastAPI

deploy

clarajob-redis

restart du cache Redis

deploy

minio-service

restart MinIO S3

deploy

minio-backup

restart du sidecar backup MinIO (mc mirror)

deploy

dozzle

restart Dozzle (logs Docker)

deploy

auth-server-db

restart PostgreSQL Keycloak + backup pre-deploy auto

deploy (repo auth-server)

keycloak

restart Keycloak + backup pre-deploy auto de sa DB

deploy (repo auth-server)

adminer

restart Adminer

deploy (repo sever-admin)

server-admin-doc

restart du Nginx de documentation

deploy (repo sever-admin)

documentation

git pull (site pré-généré en local : build/generatedSite versionné dans le repo) + restart Nginx — aucun build serveur

deploy (repo documentation)

traefik

git pull main-server-proxy + restart Traefik (image registry.gitlab.com/app81724/proxy/main-server-proxy/traefik-service:TAG si TAG)

bloc inline (avec rollback)

marketisia-sa

git pull du repo marketisia + pull images (marketisia-front-api, marketisia-front-gui) + up -d tout le stack (compose : docker/docker-compose.yml) + backup pre-deploy auto

bloc inline (avec rollback)

marketisia-front-api

restart de l’API PredictX seule

deploy (compose docker/docker-compose.yml)

marketisia-front-gui

restart de la GUI PredictX seule

deploy (compose docker/docker-compose.yml)

Exemples réels (repris du Makefile) :

make deploy APP=clarajob-sa                        # stack complet, tag latest
make deploy APP=clarajob-sa TAG=v1.2.0             # version spécifique
make deploy APP=clarajob-front-api TAG=abc1234     # un service à un commit SHA
make deploy APP=clarajob-ddl BRANCH=feature/my-branch
make deploy APP=clarajob-sa BRANCH=develop TAG=v1.2.0
make deploy APP=marketisia-sa
make deploy APP=marketisia-front-gui TAG=v1.2.0
make deploy APP=traefik TAG=v1.0.0
make deploy APP=keycloak
make deploy APP=documentation                      # pull (build/ versionné) + restart nginx
make deploy APP=clarajob-sa ENV=local              # déploiement sur ta machine

Séquence du rôle deploy (services individuels) :

  1. Git : clone si absent / git clean -fd + pull sinon (branche BRANCH ou main)

  2. docker compose stop <service>

  3. docker login registry.gitlab.com (deploy token en vault)

  4. docker compose pull <service> — seulement si TAG est fourni

  5. IMAGE_TAG=<tag> docker compose up -d <service>

  6. Pause 10s, vérifie que le container tourne (docker ps)

  7. Rescue : en cas d’échec, relance up -d (rollback) puis échoue avec message explicite

7. make setup-cron

Configure les backups automatiques sur le serveur (à lancer une seule fois).

make setup-cron

Ce que fait setup-cron.yml :

  1. Installe Ansible sur le serveur cible

  2. Copie .vault_password (racine du repo) → /opt/.vault_password sur le serveur (mode 600, root)

  3. Supprime les anciens crons WordPress (backup-clarajob-daily, backup-marketisia-daily)

  4. Crée 3 crons (utilisateur root, logs → /var/log/ansible-backup.log) :

Cron Heure Commande

backup-marketisia-sa-daily

03:00

ansible-playbook playbooks/backup.yml -e target_app=marketisia-sa

backup-clarajob-ddl-daily

04:00

ansible-playbook playbooks/backup.yml -e target_app=clarajob-ddl

backup-clarajob-mongo-daily

05:00

ansible-playbook playbooks/backup.yml -e target_app=clarajob-mongo

auth-server-db n’a pas de cron automatique — son backup se fait manuellement (make backup APP=auth-server-db) ou automatiquement en pre-deploy de keycloak/auth-server-db.

8. Équivalents Ansible Directs

Le Makefile est un simple wrapper. Tu peux appeler Ansible directement (toujours depuis le dossier ansible/ — exigé par ansible.cfg) :

cd sever-admin/ansible

# Backup
ansible-playbook playbooks/backup.yml -e target_app=clarajob-ddl

# Restore
ansible-playbook playbooks/restore.yml \
  -e "target_app=clarajob-mongo dump_file=clarajob-mongo-2026-07-26_050000.archive"

# Deploy
ansible-playbook playbooks/deploy.yml -e "target_app=clarajob-sa image_tag=v1.2.0"

# Cibler la machine locale
ansible-playbook playbooks/deploy.yml -e "target_app=clarajob-sa target_hosts=local"

Le --vault-password-file est automatique : ansible.cfg déclare vault_password_file = ~/.vault_sever_admin.

9. Diagnostics (commandes shell, PAS make)

Le Makefile ne fournit pas de commandes de logs/status. Pour diagnostiquer, connecte-toi au serveur :

# Connexion SSH (user = admin, pas debian)
ssh -i ~/.ssh/serverAdminSSHKeypair.pem admin@18.158.207.98

# Puis sur le serveur :
docker ps                                  # containers actifs
docker logs clarajob-front-api --tail 100  # logs d'un service
docker logs -f marketisia-front-api        # logs en continu
df -h                                      # espace disque
docker stats --no-stream                   # CPU/RAM par container
ls -lh /home/admin/app/sever-admin/db-config/dump/clarajob-ddl/   # dumps disponibles
cat /var/log/ansible-backup.log            # logs des backups cron
crontab -l                                 # crons actifs

Alternative sans SSH : Dozzle (logs web, port 9999), Beszel (métriques, port 8090), Grafana/Loki (logs centralisés, port 3000). Voir Monitoring.

10. Erreurs Courantes

# "❌ Usage: make backup APP=..."
→ Tu as oublié APP. Il est obligatoire, sans défaut.

# "Application 'xxx' inconnue. Apps valides : ..."
→ APP n'est pas dans la liste des 19 cibles du playbook deploy.yml.

# "ERROR! Attempting to decrypt but no vault secrets found"
→ ~/.vault_sever_admin absent ou illisible :
   echo "MotDePasseVault" > ~/.vault_sever_admin && chmod 600 ~/.vault_sever_admin

# "Le fichier dump '...' est introuvable"
→ Le DUMP doit être le nom exact d'un fichier présent dans
   db-config/dump/<service>/ (lister avec ls sur le serveur).

# "Le dump ... est vide ou n'a pas été créé"
→ Credentials DB faux dans vault.yml, ou base vide. Vérifier avec :
   ansible-vault view inventory/group_vars/all/vault.yml

11. Prochaines Étapes