From 8ec32e79313208db328058a1d4b611f115a61f7b Mon Sep 17 00:00:00 2001
From: Paul Schneider <paul@pschneider.fr>
Date: Sat, 27 Jun 2026 17:38:08 +0100
Subject: [PATCH] contributing+compose: clarify 'machine vierge' criterion for
 Jalon 0

Make explicit what was implicit: 'docker compose up' is not
expected to start everything on a bare host. Yavsc.Org (web)
requires an HTTPS signing certificate for IdentityServer8 in
Production mode, and the volume mount /etc/letsencrypt:/etc/letsencrypt:ro
is the documented way to supply it.

Two related changes:

- CONTRIBUTING.md, 'docker compose up' section: spell out that
  db + api + blogs start cleanly on a bare host, web fails with
  the documented IdentityServer error, and that the difference
  between 'vierge' and 'configured' is exactly the cert volume.
- docker-compose.yaml, web service: expand the commented volumes
  block to point at the same error message and reference the
  'HTTPS en production' section in CONTRIBUTING.md, so an
  operator reading the compose file knows what to uncomment
  and where to look.
---
 CONTRIBUTING.md     | 16 ++++++++++++++++
 Dockerfile.backend  |  2 +-
 docker-compose.yaml |  7 +++++++
 3 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index cc5d9e17..143060c2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -114,6 +114,22 @@ pointe sur le stage correspondant du Dockerfile multi-stage via
 `build.target`. Les services runtime attendent le healthcheck
 `pg_isready` de `db` avant de démarrer.
 
+**Sur une machine vierge, `db`, `api` et `blogs` démarrent. Le
+service `web` (Yavsc.Org) échoue avec :**
+
+> Production IdentityServer requires a signing certificate.
+> Configure Kestrel:Endpoints:Https:Certificate:{Path,KeyPath}.
+
+C'est attendu : IdentityServer8 en mode Production exige un cert
+HTTPS pour signer les tokens (cf. `src/Yavsc.Org/Extensions/HostingExtensions.cs:374`).
+Le critère de sortie Jalon 0 « docker compose up vert sur machine
+vierge » n'est donc **pas** « tout démarre sans rien » — c'est
+« tout démarre **après** la procédure d'installation qui monte
+un cert HTTPS valide, cf. HTTPS en production ci-dessous ».
+Le montage de `/etc/letsencrypt` (volume commenté par défaut
+dans `docker-compose.yaml`) est l'étape qui distingue une
+machine configurée d'une machine vierge.
+
 ### appsettings-org.json
 
 Le fichier de configuration de prod (`src/Yavsc.Org/appsettings-org.json`)
diff --git a/Dockerfile.backend b/Dockerfile.backend
index 09cb0774..86df9ccd 100644
--- a/Dockerfile.backend
+++ b/Dockerfile.backend
@@ -1,4 +1,4 @@
-# Utilisation de votre image globale pour le build et l'exécution
+# Utilisation de l'image globale pour le build et l'exécution
 FROM pazof/yavsc-build-env:debian12-dotnet10-android36-v1 AS build-env
 WORKDIR /src
 
diff --git a/docker-compose.yaml b/docker-compose.yaml
index 65e552fe..0b00a20f 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -56,6 +56,13 @@ services:
       - yavsc-internal
       - yavsc-public
     # volumes:
+    #   # Indispensable pour que Yavsc.Org (IdentityServer8) démarre.
+    #   # Sans ce montage, 'docker compose up' échoue côté web avec
+    #   # « Production IdentityServer requires a signing certificate ».
+    #   # Décommenter ici + côté api/blogs + renseigner
+    #   # Kestrel:Endpoints:Https:Certificate:{Path,KeyPath} dans
+    #   # appsettings-org.json (cf. section HTTPS en production dans
+    #   # CONTRIBUTING.md).
     #   - /etc/letsencrypt:/etc/letsencrypt:ro
 
   # ---------- Yavsc.Api (API REST principale) ----------