1. Qu’est-ce que sever-admin ?

sever-admin est le projet d'administration serveur pour les applications ClaraJob-SA (PostgreSQL + MongoDB + Spring Boot + Vue.js) et Marketisia-SA / PredictX (PostgreSQL + Kafka + Spring Boot + Vue.js), hébergées sur AWS Lightsail (Debian).

Il remplit deux rôles distincts :

  1. Orchestration — les opérations de backup, restore et déploiement sont gérées par Ansible via make, exécutables aussi bien vers le serveur distant que sur la machine locale (ENV=local).

  2. Infrastructure partagée — son docker-compose.yml (structure include:) héberge les services transverses : broker Kafka/RabbitMQ, Redis, UIs d’admin (Adminer, pgAdmin), monitoring (Dozzle, Beszel), observabilité (Loki, Promtail, Grafana), pilotage Ansible web (Semaphore, Rundeck) et la documentation statique.

Ce que sever-admin ne fait PAS : héberger le code des applications. Chaque application vit dans son propre repo avec son propre docker-compose — Ansible les clone/pull et pilote leur cycle de vie. Voir Architecture.

2. Démarrage

👉 Quickstart — opérationnel en 10 minutes : clé SSH, vault, make ping, premier backup.

3. Guides par Sujet

Guide Contenu

Architecture

Les 2 niveaux (orchestration + apps), les 5 repos Git, les stacks, les flux réels, les ports

Référence Commandes

Les 6 commandes make (ping, backup, restore, deploy, setup-cron, help), leurs paramètres exacts, les 19 cibles de déploiement

Déploiement

Déroulement détaillé par type de cible, backups pre-deploy automatiques, rollback, Jenkins

Backup & Restore

Les 4 bases sauvegardées, les crons (3h/4h/5h), MinIO, procédures de restauration

Infrastructure Docker

La structure include:, le détail des 7 fichiers compose, le réseau proxy_server_network, les conventions

Monitoring

Dozzle, Beszel, Loki+Promtail+Grafana, Kafka UI, RabbitMQ, RedisInsight — quel outil pour quel problème

Dépannage

Solutions aux problèmes réels : SSH, vault, deploy, DB, crons, disque, RAM, disaster recovery

Ajouter un Nouveau Projet

Intégrer un backend, un frontend, une DB, un cache au système Ansible — étape par étape

4. Structure Réelle du Projet

sever-admin/
├── Makefile                        # LE point d'entrée : 6 cibles seulement
├── Jenkinsfile                     # Pipeline CI/CD (backup pre-deploy + deploy)
├── .vault_password                 # mot de passe vault (racine, pour setup-cron)
│
├── docker-compose.yml              # include: des 7 fichiers ci-dessous
├── docker-compose.cache.yml        #   redis
├── docker-compose.broker.yml       #   kafka + zookeeper + schema-registry + rabbitmq + kafka-ui
├── docker-compose.db-admin.yml     #   adminer + pgadmin
├── docker-compose.doc.yml          #   server_admin_doc (Nginx, sert build/generatedSite)
├── docker-compose.ansible.yml      #   semaphore + rundeck
├── docker-compose.monitoring.yml   #   dozzle + beszel-hub + beszel-agent + redisinsight
├── docker-compose.observability.yml#   loki + promtail + grafana
│
├── ansible/
│   ├── ansible.cfg                 # inventory, vault_password_file, roles_path, pipelining
│   ├── inventory/
│   │   ├── hosts.yml               # production (vps-main 18.158.207.98, user admin) + local
│   │   └── group_vars/
│   │       ├── all/vars.yml        # variables publiques (chemins, services, git URLs)
│   │       ├── all/vault.yml       # 🔐 secrets chiffrés
│   │       └── local/vars.yml      # surcharges ENV=local
│   ├── playbooks/
│   │   ├── deploy.yml              # 19 cibles + backups pre-deploy + rollback
│   │   ├── backup.yml              # 4 bases + all
│   │   ├── restore.yml             # 4 bases + minio-service
│   │   └── setup-cron.yml          # crons 3h/4h/5h sur le serveur
│   └── roles/
│       ├── deploy/                 # git pull → stop → pull(si TAG) → up -d → vérif → rollback
│       ├── deploy_frontend/        # + build dans container jetable si pas de TAG
│       │                           #   (npm par défaut, gradle pour documentation)
│       ├── backup/                 # pg_dump / mongodump / mysqldump + vérif non-vide
│       ├── restore/                # psql / mongorestore --drop / mysql
│       └── restore_minio/          # mc mirror depuis le backup sidecar
│
├── db-config/
│   ├── dump/                       # ← les dumps atterrissent ici (par service)
│   └── dump_description/           # ← descriptions horodatées (auto-backup / pre-deploy)
│
├── infrastructure/
│   └── security/
│       └── serverAdminSSHKeypair.pem   # clé SSH du serveur (à copier dans ~/.ssh/)
│
├── monitoring/                     # configs loki / promtail / grafana provisioning
├── deploiement_app/                # scripts de déploiement (historique)
├── scripts-legacy/                 # anciens scripts shell (remplacés par Ansible)
├── build.gradle                    # génération du site de documentation AsciiDoc
└── README.md / CLAUDE.md           # documentation du repo

5. Concepts Clés

5.1. Infrastructure as Code

Tout est en code et versionné : les compose (topologie des services), les playbooks (procédures d’exploitation), l’inventaire (serveurs), le vault (secrets chiffrés). Résultat : opérations reproductibles, auditable par Git, exécutables par n’importe quel membre de l’équipe disposant de la clé SSH et du mot de passe vault.

5.2. Les deux environnements

ENV Groupe Ansible Cible

remote (défaut)

production

vps-main = 18.158.207.98, user admin, clé serverAdminSSHKeypair.pem

local

local

localhost en ansible_connection: local (variables surchargées par group_vars/local/)

5.3. Secrets (Ansible Vault)

  • ansible/inventory/group_vars/all/vault.yml — chiffré, contient : vault_marketisia_sa_db_*, vault_clarajob_ddl_db_*, vault_clarajob_mongo_db_*, vault_auth_server_db_*, vault_gitlab_registry_token

  • Mot de passe : ~/.vault_sever_admin (poste) / /opt/.vault_password (serveur, pour les crons)

  • Édition : cd ansible && ansible-vault edit inventory/group_vars/all/vault.yml

  • Le registry GitLab (registry.gitlab.com) est accédé avec le deploy token read-only group_registry_deploy_token

5.4. Sécurité intégrée aux opérations

  • Backup pre-deploy automatique des DBs avant tout déploiement qui les touche

  • Vérification dump non-vide — un backup vide fait échouer le playbook

  • Rollback automatique (block/rescue) sur tous les déploiements

  • no_log: true sur les tâches manipulant credentials/dumps

6. Flux Quotidien Type

# Matin : vérifier que les backups de la nuit ont tourné
ssh -i ~/.ssh/serverAdminSSHKeypair.pem admin@18.158.207.98 \
  "tail -20 /var/log/ansible-backup.log && ls -lht /home/admin/app/sever-admin/db-config/dump/clarajob-ddl/ | head -3"

# Déployer une nouvelle version validée par la CI
make backup APP=clarajob-ddl              # ceinture + bretelles (pre-deploy le fait aussi)
make deploy APP=clarajob-front-api TAG=v1.2.0

# Surveiller : Dozzle (9999) en direct, Beszel (8090) pour les ressources

7. Bonnes Pratiques du Projet

  1. Toujours passer par make/Ansible — pas de docker compose manuel en production pour les applis (les playbooks font backup pre-deploy + vérifications + rollback)

  2. Ne jamais commiter un secret en clair — tout secret va dans vault.yml

  3. Tester en local d’abord quand c’est possible : make deploy APP=…​ ENV=local

  4. TAG explicite en production — TAG=v1.2.0 plutôt que latest implicite, pour pouvoir revenir en arrière avec certitude

  5. Nettoyer les dumps régulièrement — pas de purge automatique aujourd’hui

  6. Copier les dumps hors serveur périodiquement — condition du disaster recovery

  7. Vérifier /var/log/ansible-backup.log régulièrement — un cron qui échoue est silencieux

8. Support

  • Problème → Dépannage

  • Commande → Référence Commandes

  • La source de vérité ultime reste le code : Makefile, ansible/playbooks/, docker-compose.yml

Version doc : 2.0 — alignée sur l’état réel du repo au 26 juillet 2026