From b320732ed470c00eddcd9569b8d9ffd1388a025d Mon Sep 17 00:00:00 2001
From: Paul Schneider <paul@pschneider.fr>
Date: Sat, 27 Jun 2026 17:24:26 +0100
Subject: [PATCH] contributing: document the HTTP-only env block and prod HTTPS
 recipe

Update the 'HTTPS en production' section to match the new
docker-compose layout:

- explain why the per-service environment: block pinning
  ASPNETCORE_URLS to HTTP-only and clearing ASPNETCORE_HTTPS_PORT
  is required (appsettings-org.Development.json sets
  Site.Authority to https://localhost:5001, which makes Kestrel
  auto-detect an HTTPS endpoint and crash without a cert);
- give the exact 5-step recipe to enable HTTPS in production:
  switch ASPNETCORE_URLS to a double-bind form, uncomment the
  HTTPS port, uncomment the /etc/letsencrypt volume mount, add a
  Kestrel:Endpoints:Https block in appsettings-org.json pointing
  at the Let's Encrypt fullchain.pem + privkey.pem, and rebuild
  the runtime image (since appsettings are baked via BuildKit
  secret mount).
---
 CONTRIBUTING.md | 51 +++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 41 insertions(+), 10 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index db090484..cc5d9e17 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -132,17 +132,48 @@ Compose le passe automatiquement à `docker build` via le bloc
 
 ### HTTPS en production
 
-En dev local on n'expose que HTTP. En production, sur chaque
-service runtime de `docker-compose.yaml`, décommenter :
+En dev local les services runtime sont forcés à **HTTP seul** par
+un bloc `environment` explicite dans `docker-compose.yaml` :
 
-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.
+```yaml
+environment:
+  ASPNETCORE_URLS: "http://+:5000"
+  ASPNETCORE_HTTPS_PORT: ""
+```
+
+C'est nécessaire parce que `appsettings-org.Development.json`
+positionne `Site.Authority = https://localhost:5001`, ce qui
+pousse Kestrel à essayer de binder HTTPS même sans certificat
+disponible — et échoue proprement avec « Unable to configure
+HTTPS endpoint. No server certificate was specified ».
+
+En production, sur chaque service runtime de `docker-compose.yaml` :
+
+1. Remplacer l'`environment.ASPNETCORE_URLS` par la forme double-bind
+   `http://+:5000;https://+:5001` (ou équivalent pour Api / Blogs).
+2. Décommenter le port HTTPS correspondant (`5001` pour Org,
+   `5003` pour Api, `5005` pour Blogs).
+3. Décommenter le volume `/etc/letsencrypt:/etc/letsencrypt:ro` —
+   monter le répertoire Let's Encrypt de l'hôte en lecture seule
+   pour que Kestrel accède aux fichiers `.pem`.
+4. Dans `appsettings-org.json`, ajouter un bloc `Kestrel:Endpoints`
+   pointant vers les chemins du volume monté. Exemple :
+
+   ```json
+   "Kestrel": {
+     "Endpoints": {
+       "Https": {
+         "Url": "https://+:5001",
+         "Certificate": {
+           "Path": "/etc/letsencrypt/live/yavsc.example/fullchain.pem",
+           "KeyPath": "/etc/letsencrypt/live/yavsc.example/privkey.pem"
+         }
+       }
+     }
+   }
+   ```
+5. Régénérer l'image runtime (les `appsettings` sont baked dans
+   l'image via BuildKit secret mount — cf. section appsettings-org.json).
 
 ### Bumper l'image de build