fix: keep proxy healthy during tls pending

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

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
 

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.

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;
     }