Exploitation et déploiement

Cette page décrit comment exécuter, déployer et exploiter la SIM Database. Toutes les commandes sont encapsulées dans le Makefile pour fonctionner de la même façon sous Windows cmd.exe, Git Bash et les shells POSIX.

Prérequis

Docker avec le plugin Compose (docker compose version)
GNU Make (Git Bash / MSYS2 / Chocolatey sous Windows, Xcode CLT sous macOS, apt install make sous Debian)
Node + pnpm (uniquement pour le hachage des mots de passe de seed)

Aucune installation locale de Java, PostgreSQL ou Flyway n’est requise.

Mise en place de l’environnement local

Au premier clone du dépôt :

cd sim-database
make setup      # copie .env.example vers .env si absent

Renseignez les valeurs dans .env :

Variable	Défaut	Rôle
`POSTGRES_DB`	`sim_db`	Nom de la base
`POSTGRES_USER`	`sim`	Rôle applicatif
`POSTGRES_PASSWORD`	`admin`	Mot de passe local (pas pour la production)
`POSTGRES_PORT`	`5432`	Port publié sur `127.0.0.1`
`POSTGRES_HOST`	`localhost`	Hôte utilisé par les clients

Workflow de développement local

Étape	Commande	Effet
Démarrer la base	`make up`	Compile/démarre `sim-postgres:local`, attend `pg_isready`
Arrêter la base	`make down`	Arrête le conteneur mais conserve le volume de données
Redémarrer	`make restart`	Redémarre le conteneur PostgreSQL
Voir les logs	`make logs`	Suit les logs du conteneur
Statut	`make status`	Affiche la sortie de `docker compose ps`
Appliquer les migrations	`make migrate`	Exécute Flyway sur `migrations/`
Historique des migrations	`make migration-info`	Affiche `flyway info`
Valider les migrations	`make validate`	Échoue si un fichier de migration appliqué a changé
Charger les seeds de référence	`make seed-ref`	Chargement idempotent de `seeds/reference/`
Charger les seeds dev	`make seed-dev`	Charge `seeds/dev/` et applique les hachages bcrypt
Charger les deux	`make seed`	`seed-ref` puis `seed-dev`
Bootstrap admin	`make admin`	Insère l’`ADMINISTRATEUR` de bootstrap et les hachages
Ouvrir psql	`make db`	Shell interactif dans le conteneur
Lancer les tests	`make test`	Migre puis exécute la suite pgTAP dans `tests/`
Sauvegarde	`make backup`	`pg_dump -Fc` vers `backups/sim_<ts>.dump`
Lister les sauvegardes	`make backup-list`	Liste le contenu de `backups/`
Restaurer	`make restore file=sim_<ts>.dump`	`pg_restore --clean --if-exists` (destructif)
Repartir de zéro	`make reset`	`down -v`, `up` neuf, puis `migrate` (destructif)
Tout nettoyer	`make clean`	Arrête et supprime le volume de données (destructif)

Session locale typique

make up
make migrate
make seed
make test
make db
# ... développement ...
make down

Sauvegarde et reprise

Les sauvegardes sont des dumps logiques pg_dump -Fc au format custom écrits dans backups/ sur l’hôte. Elles conviennent aux reconstructions complètes, pas à la reprise à un instant T (le PITR n’est pas configuré).

Créer une sauvegarde

make backup

Restaurer une sauvegarde

make restore file=sim_20250908_120000.dump

La restauration supprime les objets du dump et les recrée. Les données créées après la sauvegarde sont perdues. Les objets créés après la sauvegarde (par exemple des migrations plus récentes) sont laissés en place, donc make migrate peut être nécessaire ensuite.

Reconstruire depuis migrations et seeds

make clean
make up
make migrate
make seed

Utile quand le schéma a dérivé ou que vous voulez un état propre.

Déploiement VPS (Postgres mutualisé)

Le stack VPS utilise une instance PostgreSQL mutualisée déjà présente sur l’hôte. Il est destiné à l’environnement de dev/démo.

Configuration : .env.vps (depuis .env.vps.example)
Réseau : internal
Déclencheur : push sur main quand migrations/**, seeds/**, config/**, scripts/bootstrap-vps.sh ou .env.vps.example changent, ou workflow_dispatch
Runner : vps-runner
Workflow : .github/workflows/deploy.yml

Le workflow :

Restaure .env.vps depuis le secret GitHub ENV_VPS_B64.
Installe Node/pnpm et les dépendances.
Exécute scripts/bootstrap-vps.sh :
- Provisionne le rôle sim et la base sim_db de façon idempotente.
- Lance Flyway migrate avec FLYWAY_OUT_OF_ORDER=true.
- Charge seeds/reference, seeds/seed_admin_user.sql, seeds/dev et seeds/generated/10_auth_passwords.sql.

Comme c’est un environnement de développement, les seeds dev et les mots de passe de démo sont acceptables.

Déploiement production (Postgres dédié)

Le stack de production est un conteneur dédié joignable par le backend sur postgres-prod:5432 dans prod-network.

Configuration : .env.prod (depuis .env.prod.example)
Déclencheur : workflow_dispatch uniquement, avec un confirm saisi et un reviewer requis sur l’environnement production
Runner : gsg-prod
Workflow : .github/workflows/deploy-prod.yml

Le workflow :

make prod-up — compile/démarre sim-postgres-prod.
make prod-migrate — applique les migrations Flyway.
make prod-seed — charge seeds/reference/, l’admin de bootstrap et un hachage bcrypt généré en mémoire depuis ADMIN_LOGIN/ADMIN_PASSWORD dans .env.prod.
make prod-admin-ui-up — démarre/met à jour pgAdmin derrière Traefik (optionnel).

prod-seed ne charge jamais seeds/dev/. Le mot de passe admin de production est haché par scripts/hash-prod-admin.mjs et pipé vers psql ; il n’est jamais loggé ni commité.

Commandes de production

make prod-up
make prod-migrate
make prod-seed
make prod-db
make prod-backup
make prod-admin-ui-up

pgAdmin (production)

Le profil pgadmin dans docker-compose.prod.yml expose pgAdmin derrière Traefik sur https://${PGADMIN_HOST}. Il n’est pas démarré par prod-up ; démarrez-le explicitement avec :

make prod-admin-ui-up

Le serveur pré-enregistré dans docker/pgadmin/servers.json se connecte à postgres-prod:5432 / sim_db.

Pipelines CI/CD

Workflow	Déclencheur	Runner	Rôle
`ci.yml`	`push: main`, `pull_request`	`ubuntu-latest`	Démarre le stack compose local, migre et exécute `make test`
`deploy.yml`	`push: main` sur les chemins DB ou `workflow_dispatch`	`vps-runner`	Bootstrap/migre/seed le Postgres mutualisé du VPS
`deploy-prod.yml`	`workflow_dispatch` avec approbation manuelle	`gsg-prod`	Déploie le Postgres de production dédié

Les deux workflows de déploiement décodent tout le fichier .env depuis un secret base64 et lui appliquent chmod 600. Le workflow de production supprime .env.prod dans une étape always().

Hors périmètre assumé

Sauvegarde WAL/PITR (seul wal_level=replica est préconfiguré)
Stack de monitoring native
Multi-maître ou réplicas en lecture

Ces points sont laissés au jalon plus large sim-backend/hébergement.

Démonstrations de commandes

Partir de zéro

$ cd sim-database
$ make setup
Created .env from .env.example

$ make up
[+] Running 2/2
 ✔ Container sim-database-postgres-1  Started

$ make migrate
Flyway ...
Successfully applied 73 migrations.

$ make seed
-> reference seeds loaded
-> dev seeds loaded
-> bcrypt hashes applied

$ make test
000_smoke.sql ........................ PASS
010_regles_transverses.sql ........... PASS
020_regles_residence.sql ............. PASS
030_regles_market.sql ................ PASS
040_regles_pressing_restaurant_fete.sql  PASS
050_regles_rh.sql .................... PASS
060_regles_dynamiques_residence.sql .. PASS
070_regles_dynamiques_market.sql ..... PASS
080_regles_dynamiques_finances.sql ... PASS
090_regles_dynamiques_rh.sql ......... PASS
100_audit.sql ........................ PASS
110_auth.sql ......................... PASS
120_resident_portal.sql .............. PASS

Ajouter une nouvelle migration et la tester

# 1. Créer le nouveau fichier de migration
$ touch migrations/residence/074_residence_demande_maintenance.sql

# 2. Écrire le DDL, sauvegarder, puis migrer
$ make migrate
Flyway ...
Current version: 73
+---------+ ...
| 074 ... | ...
+---------+ ...

# 3. Lancer les tests pour vérifier que rien n'est cassé
$ make test

# 4. Ouvrir psql pour vérifier
$ make db
sim=# \dt residence.*

Ce qu’il ne faut pas faire en exploitation

Ne pas faire	Pourquoi	À la place
Modifier `migrations/common/001_bootstrap_schemas.sql`	Elle a déjà été appliquée	Ajouter une nouvelle migration
Lancer `make seed-dev` sur le stack compose de production	`prod-seed` est la seule commande de seed sûre en production	`make prod-seed`
Lancer `make restore` sur une base de production en heures ouvrées	Elle supprime les objets et restaure le dump ; interruption	Planifier une fenêtre de maintenance
Commiter `.env` ou `.env.prod`	Des secrets dans Git sont un risque de sécurité	Utiliser les modèles `.env.example` et les secrets GitHub
Lancer `make clean` en espérant garder les données	Il supprime le volume Docker	Utiliser `make down` pour arrêter, `make backup` avant `make clean`