Ajout des commentaires dans le code

docs/README_DOCKER.md

@@ -0,0 +1,129 @@
+# PTA - Docker / Nginx / PHP / MariaDB / phpMyAdmin
+
+## Installation
+
+Copier les fichiers de ce kit à la racine du projet PTA :
+
+- `Dockerfile`
+- `docker-compose.yml`
+- `.env.example`
+- `docker/nginx/default.conf`
+- `docker/php/php.ini`
+- `docker/db/apply-migrations.sh`
+- `database/pta_prod_schema_mariadb.sql`
+- `database/migration_*.sql`
+
+Puis :
+
+```bash
+cp .env.example .env
+nano .env
+```
+
+Changer impérativement `DB_PASSWORD` et `DB_ROOT_PASSWORD`.
+
+Démarrer :
+
+```bash
+docker compose up -d --build
+```
+
+Application :
+
+```text
+http://IP_DU_SERVEUR:8080
+```
+
+phpMyAdmin est volontairement publié sur `127.0.0.1:8081` par défaut et **exige
+un identifiant MariaDB** à chaque connexion. Ne pas définir `PMA_USER` /
+`PMA_PASSWORD` dans le compose : ces variables font basculer phpMyAdmin en
+`auth_type=config`, c'est-à-dire une session déjà ouverte pour quiconque
+atteint le port.
+
+Sur le serveur lui-même :
+
+```text
+http://127.0.0.1:8081
+```
+
+Pour y accéder depuis un poste distant, le plus sûr est un tunnel SSH :
+
+```bash
+ssh -L 8081:127.0.0.1:8081 utilisateur@serveur
+```
+
+Puis ouvrir localement :
+
+```text
+http://127.0.0.1:8081
+```
+
+## Base de données
+
+Le schéma `database/pta_prod_schema_mariadb.sql` est exécuté automatiquement uniquement
+lorsque le volume MariaDB est créé pour la première fois.
+
+Il ne sera PAS rejoué à chaque démarrage du conteneur.
+
+### Migrations
+
+Les fichiers `database/migration_*.sql` sont appliqués **automatiquement à chaque
+`docker compose up`**, par le service jetable `db-migrate` :
+
+- il attend que MariaDB soit sain, puis joue les migrations dans l'ordre alphabétique ;
+- la table `schema_migration` mémorise les fichiers déjà appliqués — rien n'est rejoué
+  inutilement ;
+- le service `php` ne démarre qu'après sa sortie en succès : une migration en échec arrête
+  le déploiement au lieu de faire tourner l'application sur une base incomplète ;
+- il vérifie pour finir la présence des sept vues de contrôle d'accès de la V7.8.
+
+Il n'est donc plus nécessaire de supprimer le volume ni d'exécuter les migrations à la main.
+
+```bash
+# Compte rendu de la dernière application
+docker compose logs db-migrate
+
+# Rejouer les migrations sans toucher au reste de la pile
+docker compose up -d --force-recreate db-migrate
+```
+
+Toute nouvelle migration doit être écrite idempotente (`CREATE TABLE IF NOT EXISTS`,
+`INSERT ... ON DUPLICATE KEY UPDATE`, `CREATE OR REPLACE VIEW`) : un fichier dont le contenu
+change après coup est rejoué.
+
+## Commandes utiles
+
+```bash
+# Etat
+docker compose ps
+
+# Logs
+docker compose logs -f nginx php db
+
+# Rebuild après modification du PHP / JS / CSS
+docker compose up -d --build php nginx
+
+# Journal de l'application des migrations
+docker compose logs db-migrate
+
+# Arrêt
+docker compose down
+
+# Arrêt SANS supprimer les données
+docker compose down
+
+# ATTENTION : supprime la base MariaDB persistée
+docker compose down -v
+```
+
+## Connexion de l'application
+
+Le `config.php` PTA utilise déjà les variables :
+
+- `PTA_DB_HOST`
+- `PTA_DB_PORT`
+- `PTA_DB_NAME`
+- `PTA_DB_USER`
+- `PTA_DB_PASS`
+
+Le compose les fournit automatiquement au conteneur PHP.