Objectif

En 10 minutes, tu seras capable de :

  1. Cloner et configurer le repo sever-admin

  2. Te connecter au serveur AWS Lightsail

  3. Lancer ton premier backup

  4. Comprendre les commandes disponibles

Étape 1 : Prérequis (2 min)

Installe ces outils sur ta machine (Debian/Ubuntu) :

sudo apt install ansible-core git make
# Docker uniquement si tu veux tester en local (ENV=local)

Vérification :

ansible --version
make --version
git --version

Étape 2 : Cloner le Repo (1 min)

git clone git@gitlab.com:app81724/sever-admin.git
cd sever-admin

Étape 3 : Configurer la Clé SSH (2 min)

La clé du serveur est dans le repo (infrastructure/security/) :

cp infrastructure/security/serverAdminSSHKeypair.pem ~/.ssh/
chmod 400 ~/.ssh/serverAdminSSHKeypair.pem

# Tester — l'utilisateur est "admin" (défini dans ansible/inventory/hosts.yml)
ssh -i ~/.ssh/serverAdminSSHKeypair.pem admin@18.158.207.98 "echo OK"
# Attendu : OK

Serveur

AWS Lightsail (Debian)

IP

18.158.207.98 (host Ansible : vps-main)

Utilisateur SSH

admin

Clé

~/.ssh/serverAdminSSHKeypair.pem

Étape 4 : Configurer Ansible Vault (2 min)

Les secrets (mots de passe DB, token registry GitLab) sont chiffrés dans ansible/inventory/group_vars/all/vault.yml. Le mot de passe Vault vit hors du repo :

# Créer le fichier de mot de passe (demande le mot de passe au team lead)
echo "MotDePasseVault" > ~/.vault_sever_admin
chmod 600 ~/.vault_sever_admin

Le chemin ~/.vault_sever_admin est codé en dur dans le Makefile et dans ansible/ansible.cfg (vault_password_file = ~/.vault_sever_admin). Le fichier doit être sur un filesystem Linux (pas NTFS) pour éviter les problèmes de permissions.

Vérifier que tu peux lire les secrets :

cd ansible
ansible-vault view inventory/group_vars/all/vault.yml
# Doit afficher les vault_* en clair. Erreur "Vault password did not match" = mauvais mot de passe.
cd ..

Étape 5 : Tester la Connexion Ansible (1 min)

make ping
# Attendu :
# vps-main | SUCCESS => { ..., "ping": "pong" }

Étape 6 : Premier Backup (2 min)

make backup APP=clarajob-ddl

Ce qui se passe : Ansible se connecte au serveur, exécute pg_dump dans le container clarajob-ddl, et écrit le dump sur le serveur dans :

/home/admin/app/sever-admin/db-config/dump/clarajob-ddl/clarajob-ddl-2026-07-26_143012.sql

La confirmation Ansible affiche le chemin et la taille du dump. Un dump vide fait échouer le playbook (protection intégrée).

Les 6 Commandes du Makefile

C’est tout ce qui existe — il n’y a pas d’autres cibles :

make help                                            # aide
make ping                                            # test connexion
make backup APP=clarajob-ddl|clarajob-mongo|marketisia-sa|auth-server-db|all
make restore APP=clarajob-ddl DUMP=clarajob-ddl-2026-07-26_040000.sql
make deploy APP=<une-des-19-cibles> [TAG=v1.2.0] [BRANCH=develop]
make setup-cron                                      # installer les crons de backup (1 fois)

Ajouter ENV=local à backup/restore/deploy/setup-cron pour cibler ta machine au lieu du serveur.

→ Détail complet de chaque commande : Référence Commandes

Cas d’Utilisation Courants

« Je déploie une nouvelle version de l’API ClaraJob »

make deploy APP=clarajob-front-api TAG=v1.2.0
# Backup pre-deploy automatique : non (seules les DBs en ont)
# git pull, docker pull du tag, restart, vérification, rollback auto si échec

« Je déploie tout le stack ClaraJob »

make deploy APP=clarajob-sa
# Backups pre-deploy AUTOMATIQUES de clarajob-ddl (PostgreSQL) et clarajob-mongo (MongoDB),
# puis git pull + pull des 4 images GitLab + docker compose up -d

« Je publie la documentation des projets »

make deploy APP=documentation
# git pull du repo documentation (build/ pré-généré et versionné) + restart nginx
# → https://documentation.clarajob.com / .marketisia.com / .pretydate.com
# Pas de TAG possible ni de build serveur : générer en local (gradle asciidoctor),
# committer build/ puis déployer

« Je dois restaurer la base après un incident »

# 1. Lister les dumps disponibles (sur le serveur)
ssh -i ~/.ssh/serverAdminSSHKeypair.pem admin@18.158.207.98 \
  "ls -lht /home/admin/app/sever-admin/db-config/dump/clarajob-ddl/ | head"

# 2. Restaurer
make restore APP=clarajob-ddl DUMP=clarajob-ddl-2026-07-26_040000.sql

« Je veux voir les logs d’un service »

# Option 1 : SSH
ssh -i ~/.ssh/serverAdminSSHKeypair.pem admin@18.158.207.98
docker logs clarajob-front-api --tail 100

# Option 2 : Dozzle (interface web logs Docker) — port 9999
# Option 3 : Grafana + Loki (logs centralisés) — port 3000

Quand T’es Bloqué

Symptôme Solution

Vault password did not match

Mauvais mot de passe dans ~/.vault_sever_admin — demande le bon au team lead

Permission denied (publickey)

chmod 400 ~/.ssh/serverAdminSSHKeypair.pem ; vérifie que tu utilises bien admin@

❌ Usage: make backup APP=…​

APP est obligatoire, sans valeur par défaut

Application 'xxx' inconnue

APP hors liste — voir les 19 cibles dans la référence

Une commande make n’existe pas

Normal : seuls help, ping, backup, restore, deploy, setup-cron existent

Plus de cas : Dépannage.

Prochaines Étapes

  1. Comprendre l’architecture → Architecture

  2. Maîtriser les déploiements → Déploiement

  3. Backups & restauration → Backup & Restore

  4. Toutes les commandes → Référence Commandes

✅ Tu es opérationnel. Bienvenue ! 🚀