From ad1e4a6f4e1122f59030a5d74de589fb7065d52f Mon Sep 17 00:00:00 2001
From: Paul Schneider <paul@pschneider.fr>
Date: Sat, 27 Jun 2026 16:28:05 +0100
Subject: [PATCH] contributing: document containerisation (compose, secrets,
 HTTPS bump)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a 'Conteneurisation' section covering:

- the three image families (build env, runtime per project);
- the yavsc-build-env pin on Docker Hub and the
  dotnet-android-build-image sibling repo;
- the docker compose up flow (4 services, healthcheck-gated);
- how appsettings-org.json is injected via BuildKit secret mount
  (file remains on the host, never lands in a layer);
- the HTTPS-in-prod recipe (uncomment ports 5001/5003/5005 +
  /etc/letsencrypt volume + Kestrel:Certificates in
  appsettings-org.json + ASPNETCORE_URLS override);
- the bump procedure when the build-env image is rebuilt
  (rebuild + push with new tag, then update Dockerfile,
  Dockerfile.backend, the three Dockerfile.runtime*, and
  docker-compose.yaml in lockstep);
- an isolated build/run check for one runtime image.

Also corrects an outdated mention of 'build.args.BUILD_ENV_IMAGE'
(removed in the previous commit) — the lockstep list now points
at the docker-compose 'build' blocks instead.
---
 CONTRIBUTING.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index db6c0d45..374f1b84 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -82,6 +82,92 @@ Quelques règles non capturées par `.editorconfig` :
 
 Cf. [doc/architecture/decoupage-organisation.md](./doc/architecture/decoupage-organisation.md).
 
+## Conteneurisation
+
+Le repo expose trois images Docker :
+
+| Dockerfile              | Cible                                                       | Construite par                                  |
+|-------------------------|-------------------------------------------------------------|-------------------------------------------------|
+| `Dockerfile`            | Image de build (Debian + .NET 10 + Android SDK 36). Sert aussi à produire l'APK Android. | `.github/workflows/docker-publish-android.yml` |
+| `Dockerfile.backend`    | Idem, mais ne publie que `Yavsc.Org` (build + publish artifact). | `.github/workflows/docker-publish-backend.yml` |
+| `Dockerfile.runtime*`   | Images runtime ASP.NET pour `Yavsc.Org` (5000), `Yavsc.Blogs` (5004), `Yavsc.Api` (5002). | `docker compose build`                          |
+
+L'image de build est construite depuis le dépôt sibling
+`dotnet-android-build-image` (Debian 12 + .NET 10 SDK + Android
+SDK 36 + workload .NET Android). Elle est poussée sur Docker Hub
+sous le tag `pazof/yavsc-build-env:debian12-dotnet10-android36-v1`.
+Tous les `Dockerfile.runtime*` et les `Dockerfile` /
+`Dockerfile.backend` référencent ce tag — le bumper en lockstep
+quand l'image de build est reconstruite.
+
+### `docker compose up`
+
+```bash
+sudo docker compose up --build
+```
+
+Cela démarre 4 services : `db` (PostgreSQL 16), `web` (Yavsc.Org),
+`api` (Yavsc.Api), `blogs` (Yavsc.Blogs). Les services runtime
+s'attendent via `depends_on.condition: service_healthy` sur le
+healthcheck `pg_isready` de `db`.
+
+### appsettings-org.json
+
+Le fichier de configuration de prod (`src/Yavsc.Org/appsettings-org.json`)
+n'est **pas** commité. Il est injecté dans chaque image runtime
+via un **BuildKit secret mount** — le fichier reste sur l'hôte,
+n'apparaît dans aucun layer :
+
+```yaml
+secrets:
+  yavsc_appsettings:
+    file: ./src/Yavsc.Org/appsettings-org.json
+```
+
+Compose le passe automatiquement à `docker build` via le bloc
+`build.secrets` de chaque service runtime.
+
+### HTTPS en production
+
+En dev local on n'expose que HTTP. En production, sur chaque
+service runtime de `docker-compose.yaml`, décommenter :
+
+1. Le port HTTPS correspondant (`5001` pour Org, `5003` pour Api,
+   `5005` pour Blogs).
+2. Le volume `/etc/letsencrypt:/etc/letsencrypt:ro`.
+3. Dans `appsettings-org.json`, renseigner
+   `Kestrel:Certificates:Default:Path` et `:KeyPath` pour pointer
+   vers les fichiers Let's Encrypt du volume monté.
+4. Surcharger `ASPNETCORE_URLS` pour écouter à la fois HTTP et
+   HTTPS.
+
+### Bumper l'image de build
+
+Quand on bumpe Debian, .NET SDK ou Android SDK, reconstruire
+l'image de base :
+
+```bash
+cd ../dotnet-android-build-image
+docker build -t pazof/yavsc-build-env:debian12-dotnet10-android36-v2 .
+docker push pazof/yavsc-build-env:debian12-dotnet10-android36-v2
+```
+
+Puis bumper en lockstep dans :
+- `Dockerfile`, `Dockerfile.backend`
+- `Dockerfile.runtime`, `Dockerfile.runtime.blogs`, `Dockerfile.runtime.api`
+- `docker-compose.yaml` (chaque bloc `build` qui pointe sur un
+  `Dockerfile.runtime*`).
+
+### Vérifier un build isolé d'une image runtime
+
+```bash
+docker build \
+  --secret id=yavsc_appsettings,src=src/Yavsc.Org/appsettings-org.json \
+  -f Dockerfile.runtime \
+  -t yavsc-org:dev .
+docker run --rm -p 5000:5000 yavsc-org:dev
+```
+
 ## Sessions DDD
 
 Le repo tient un journal de design DDD sous `doc/ddd-exploration-*.md`