feat(deploy): expose a /health endpoint

deployment/README.md

@@ -4,7 +4,7 @@ This stack runs one relay instance behind an nginx reverse proxy:
 
 - `relay` renders its configuration from the templates in `configs/relay`,
   serves the WebSocket protocol on `RELAY_PORT`, and answers probes on
-  `HEALTH_PORT`.
+  `HEALTH_PORT`. nginx publishes only the liveness probe, at `/health`.
 - `nginx` is the only published service. It upgrades WebSocket connections to
   the relay and forwards everything else to it.
 
@@ -78,9 +78,11 @@ container, so it can be inspected with
 - `GET /ready` on `HEALTH_PORT` is readiness; `503` means the relay can no
   longer serve sessions.
 
-The compose healthcheck polls `/ready` inside the relay container. Keep
-`HEALTH_PORT` off the public interface: it needs no authentication and reports
-session counts.
+nginx proxies `GET /health` on the published port, so a load balancer or uptime
+check can poll `http://<host>:<RELAY_PUBLIC_PORT>/health`. It does not proxy
+`/ready`, which reports session and connection counts: that endpoint is for the
+orchestrator, so keep `HEALTH_PORT` off the public interface. The compose
+healthcheck polls `/ready` inside the relay container.
 
 ## TLS
 

deployment/configs/compose.env.example

@@ -12,6 +12,7 @@ APPLICATION_AUDIENCE=wss://relay.example.com
 RELAY_PUBLIC_PORT=8080
 
 # Ports inside the relay container: the WebSocket listener and the probes.
+# nginx proxies only /health from the probe port; /ready stays internal.
 RELAY_PORT=8080
 HEALTH_PORT=8081
 

deployment/configs/nginx/default.conf.template

@@ -26,6 +26,14 @@ server {
     access_log /dev/stdout relay;
     error_log /dev/stderr crit;
 
+    location = /health {
+        proxy_pass http://relay:${HEALTH_PORT};
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
     location / {
         limit_conn perip ${PER_IP_CONNECTIONS};
         limit_req  zone=perip_rate burst=${PER_IP_BURST} nodelay;

deployment/docker-compose.yml

@@ -25,6 +25,7 @@ services:
         condition: service_healthy
     environment:
       RELAY_PORT: ${RELAY_PORT}
+      HEALTH_PORT: ${HEALTH_PORT}
       PER_IP_CONNECTIONS: ${PER_IP_CONNECTIONS:-64}
       PER_IP_RATE: ${PER_IP_RATE:-5}
       PER_IP_BURST: ${PER_IP_BURST:-20}