From 0302634094d34078152b3c01a501e42753ae07af Mon Sep 17 00:00:00 2001
From: bisco <bisco@younerd.org>
Date: Thu, 25 Jun 2026 12:00:33 +0200
Subject: [PATCH] fix: keep proxy healthy during tls pending

---
 README.md          |  9 +++++++++
 docs/deployment.md |  7 ++++---
 docs/runbook.md    | 19 +++++++++++++++++++
 nginx/default.conf |  7 +++++++
 4 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 606e3be..00b50f3 100644
--- a/README.md
+++ b/README.md
@@ -102,6 +102,15 @@ TRUST_PROXY_HEADERS=0
 Before the first certificate exists, NGINX serves ACME challenges and returns 503 for
 application traffic. After issuance, HTTP redirects to HTTPS automatically.
 
+Run the real bootstrap without the test override:
+
+```bash
+docker compose --profile tools run --rm wp-cli /scripts/bootstrap.sh
+```
+
+The `docker-compose.test.yml` override intentionally uses disposable test volumes; do
+not use it for production or staging bootstrap commands.
+
 ## Useful commands
 
 ```bash
diff --git a/docs/deployment.md b/docs/deployment.md
index c3f1d0b..cfa0b8e 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -42,9 +42,10 @@ is safe only when firewall/network policy makes the load balancer the sole NGINX
 caller and it overwrites `X-Forwarded-*` headers.
 
 For direct TLS, public DNS and inbound ports 80/443 must reach NGINX. Start with
-`LETSENCRYPT_STAGING=1`; application HTTP returns 503 until a certificate exists, then
-redirects to HTTPS. Switch to the production CA only after validating DNS and firewall
-behavior, removing only the staging certificate volume when necessary.
+`LETSENCRYPT_STAGING=1` and set `WP_URL` to the final HTTPS URL. Application HTTP
+returns 503 until a certificate exists, then redirects to HTTPS. Switch to the
+production CA only after validating DNS and firewall behavior, removing only the
+staging certificate directory when necessary.
 
 ## State and rollback
 
diff --git a/docs/runbook.md b/docs/runbook.md
index 958c96b..d8cea0b 100644
--- a/docs/runbook.md
+++ b/docs/runbook.md
@@ -31,6 +31,25 @@ Verify public DNS, inbound port 80, the operator email, and staging mode. Reques
 missing `/.well-known/acme-challenge/` path: an NGINX 404 confirms the route is yours.
 Avoid repeated production-CA retries while debugging.
 
+When Let's Encrypt is enabled, the proxy intentionally returns 503 for normal
+application paths until a certificate exists. ACME challenge paths and proxy health
+paths must still work in that pending state, otherwise Certbot will never start.
+
+## Bootstrap writes to the wrong data volume
+
+Do not combine the test override with production bootstrap commands. This command writes
+to isolated test volumes only:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.test.yml --profile tools run --rm wp-cli /scripts/bootstrap.sh
+```
+
+Use this command for the real host-based WordPress data directory:
+
+```bash
+docker compose --profile tools run --rm wp-cli /scripts/bootstrap.sh
+```
+
 ## Rollback
 
 Revert the deployment commit and rebuild while preserving all host data directories.
diff --git a/nginx/default.conf b/nginx/default.conf
index 4367fb5..a5a2f37 100644
--- a/nginx/default.conf
+++ b/nginx/default.conf
@@ -29,10 +29,17 @@ server {
         access_log off;
         allow 127.0.0.1;
         deny all;
+        proxy_intercept_errors on;
+        error_page 301 302 303 307 308 = @wordpress-health-ok;
         proxy_set_header Host __DOMAIN__;
         proxy_pass http://wordpress_backend/wp-login.php;
     }
 
+    location @wordpress-health-ok {
+        access_log off;
+        return 204;
+    }
+
     location / {
         return 404;
     }