feat: add backend health checks

README.md

@@ -13,22 +13,46 @@ Docker Compose deployment for Traefik used as a TCP load balancer with TLS passt
 
 ## Configuration
 
-Edit SNI routes and backend targets in `config/dynamic/tcp-services.yml`:
+Add or edit one file per site under `config/dynamic/`. For example, `config/dynamic/lab-younerd.yml` contains:
 
 ```yaml
+http:
+  routers:
+    lab-younerd-http:
+      entryPoints:
+        - web
+      rule: "Host(`lab.younerd.org`)"
+      service: lab-younerd-http
+
+  services:
+    lab-younerd-http:
+      loadBalancer:
+        healthCheck:
+          path: "/"
+          hostname: "lab.younerd.org"
+          interval: "10s"
+          timeout: "3s"
+        servers:
+          - url: "http://127.0.0.1:8080"
+
 tcp:
   routers:
-    lab-younerd:
+    lab-younerd-tls:
+      entryPoints:
+        - tls
       rule: "HostSNI(`lab.younerd.org`)"
-      service: lab-younerd
+      service: lab-younerd-tls
       tls:
         passthrough: true
 
   services:
-    lab-younerd:
+    lab-younerd-tls:
       loadBalancer:
+        healthCheck:
+          interval: "10s"
+          timeout: "3s"
         servers:
-          - address: "host.docker.internal:8443"
+          - address: "127.0.0.1:8443"
 ```
 
 `HostSNI(...)` matches the hostname sent by the client during the TLS handshake. This deployment uses host networking so Traefik can reach services bound to the Docker host loopback address, such as `127.0.0.1:8443`.
@@ -43,6 +67,8 @@ www.azionelab.org -> 127.0.0.1:9080
 
 Adjust `8080` and `9080` to the local ports where the backend HTTP service is listening. The full HTTP request is forwarded so the backend can handle redirects and ACME challenge paths.
 
+Each backend service includes health checks. TCP checks verify that the TLS port accepts connections; HTTP checks call `/` with the configured hostname and treat successful or redirect responses as healthy.
+
 ## Run
 
 Validate the Compose file:

config/dynamic/azionelab.yml

@@ -0,0 +1,37 @@
+http:
+  routers:
+    azionelab-http:
+      entryPoints:
+        - web
+      rule: "Host(`azionelab.org`) || Host(`www.azionelab.org`)"
+      service: azionelab-http
+
+  services:
+    azionelab-http:
+      loadBalancer:
+        healthCheck:
+          path: "/"
+          hostname: "azionelab.org"
+          interval: "10s"
+          timeout: "3s"
+        servers:
+          - url: "http://127.0.0.1:9080"
+
+tcp:
+  routers:
+    azionelab-tls:
+      entryPoints:
+        - tls
+      rule: "HostSNI(`azionelab.org`) || HostSNI(`www.azionelab.org`)"
+      service: azionelab-tls
+      tls:
+        passthrough: true
+
+  services:
+    azionelab-tls:
+      loadBalancer:
+        healthCheck:
+          interval: "10s"
+          timeout: "3s"
+        servers:
+          - address: "127.0.0.1:9443"

config/dynamic/lab-younerd.yml

@@ -0,0 +1,37 @@
+http:
+  routers:
+    lab-younerd-http:
+      entryPoints:
+        - web
+      rule: "Host(`lab.younerd.org`)"
+      service: lab-younerd-http
+
+  services:
+    lab-younerd-http:
+      loadBalancer:
+        healthCheck:
+          path: "/"
+          hostname: "lab.younerd.org"
+          interval: "10s"
+          timeout: "3s"
+        servers:
+          - url: "http://127.0.0.1:8080"
+
+tcp:
+  routers:
+    lab-younerd-tls:
+      entryPoints:
+        - tls
+      rule: "HostSNI(`lab.younerd.org`)"
+      service: lab-younerd-tls
+      tls:
+        passthrough: true
+
+  services:
+    lab-younerd-tls:
+      loadBalancer:
+        healthCheck:
+          interval: "10s"
+          timeout: "3s"
+        servers:
+          - address: "127.0.0.1:8443"

config/dynamic/tcp-services.yml

@@ -1,53 +0,0 @@
-http:
-  routers:
-    lab-younerd-acme:
-      entryPoints:
-        - web
-      rule: "Host(`lab.younerd.org`)"
-      service: lab-younerd-acme
-
-    azionelab-acme:
-      entryPoints:
-        - web
-      rule: "Host(`azionelab.org`) || Host(`www.azionelab.org`)"
-      service: azionelab-acme
-
-  services:
-    lab-younerd-acme:
-      loadBalancer:
-        servers:
-          - url: "http://127.0.0.1:8080"
-
-    azionelab-acme:
-      loadBalancer:
-        servers:
-          - url: "http://127.0.0.1:9080"
-
-tcp:
-  routers:
-    lab-younerd:
-      entryPoints:
-        - tls
-      rule: "HostSNI(`lab.younerd.org`)"
-      service: lab-younerd
-      tls:
-        passthrough: true
-
-    azionelab:
-      entryPoints:
-        - tls
-      rule: "HostSNI(`azionelab.org`) || HostSNI(`www.azionelab.org`)"
-      service: azionelab
-      tls:
-        passthrough: true
-
-  services:
-    lab-younerd:
-      loadBalancer:
-        servers:
-          - address: "127.0.0.1:8443"
-
-    azionelab:
-      loadBalancer:
-        servers:
-          - address: "127.0.0.1:9443"

docs/adr/0001-traefik-tcp-tls-passthrough.md

@@ -20,7 +20,7 @@ Traefik routes incoming TLS connections with `HostSNI(...)` to the configured TC
 
 TLS certificates, private keys, and certificate renewal remain the responsibility of each backend. Traefik can route TLS traffic based on the TLS SNI value but cannot inspect HTTP headers or paths because TLS is passed through unchanged.
 
-Backend health is limited to TCP reachability unless protocol-specific health checks are added later. Configuration changes in `config/dynamic/` are watched by Traefik and can be applied without recreating the container.
+Backend health checks are configured per site. TCP health checks verify backend port reachability; HTTP health checks call `/` with the configured hostname. Configuration changes in `config/dynamic/` are watched by Traefik and can be applied without recreating the container.
 
 ## Alternatives considered
 
@@ -34,7 +34,7 @@ The container does not mount the Docker socket, does not run privileged, drops L
 
 ## Operational impact
 
-Operators update backend IP addresses and ports in `config/dynamic/tcp-services.yml`. Traefik listens directly on host `80/tcp` and `443/tcp`; the ping entrypoint is used by the healthcheck.
+Operators update backend IP addresses and ports in per-site files under `config/dynamic/`. Traefik listens directly on host `80/tcp` and `443/tcp`; the ping entrypoint is used by the healthcheck.
 
 ## Rollback
 

docs/architecture.md

@@ -6,7 +6,7 @@ This project runs Traefik Proxy as a Dockerized TCP load balancer.
 
 - `compose.yaml`: defines the Traefik container, host networking, host-based configuration volume, container hardening, and healthcheck.
 - `config/traefik.yml`: static Traefik configuration for HTTP, TCP TLS, ping, file provider, and logging.
-- `config/dynamic/tcp-services.yml`: dynamic HTTP challenge routers, TCP routers, and backend load-balancer services.
+- `config/dynamic/*.yml`: dynamic per-site HTTP routers, TCP routers, and backend load-balancer services.
 
 ## Data flow
 

docs/deployment.md

@@ -8,7 +8,7 @@
 
 ## Configuration
 
-Update `config/dynamic/tcp-services.yml` with the required SNI hostnames and backend addresses:
+Add or update a per-site file under `config/dynamic/` with the required hostnames and backend addresses:
 
 ```yaml
 tcp:
@@ -28,7 +28,9 @@ tcp:
 
 This deployment uses host networking so Traefik can reach services bound to host loopback addresses such as `127.0.0.1:8443`.
 
-HTTP traffic is routed separately with HTTP `Host(...)` rules on port `80`. Configure the HTTP services in `config/dynamic/tcp-services.yml` to point at the local backend port that should handle redirects and ACME challenge paths.
+HTTP traffic is routed separately with HTTP `Host(...)` rules on port `80`. Configure the HTTP service in the same per-site file to point at the local backend port that should handle redirects and ACME challenge paths.
+
+Keep each site's HTTP and TCP routers in the same dynamic file, for example `config/dynamic/lab-younerd.yml` or `config/dynamic/azionelab.yml`.
 
 The `./config` directory is the host-based configuration volume. It is mounted read-only into the container:
 

docs/operations.md

@@ -24,7 +24,7 @@ Dynamic configuration changes under `config/dynamic/` are watched by Traefik and
 
 ## Health checks
 
-The container healthcheck runs:
+The Traefik container healthcheck runs:
 
 ```bash
 traefik healthcheck --ping
@@ -36,6 +36,8 @@ Check health with:
 docker compose ps
 ```
 
+Backend services also define Traefik load-balancer health checks in each file under `config/dynamic/`. HTTP checks call `/` with the configured hostname; TCP checks verify that the local TLS port accepts connections.
+
 ## Logs
 
 Traefik logs to container stdout:
@@ -46,11 +48,11 @@ docker compose logs -f traefik
 
 ## Backend maintenance
 
-To remove a backend from rotation, edit `config/dynamic/tcp-services.yml` and remove or comment out its `address` entry. Keep at least one reachable backend configured before applying the change.
+To remove a backend from rotation, edit that site's file under `config/dynamic/` and remove or comment out its `address` entry. Keep at least one reachable backend configured before applying the change.
 
 This deployment uses host networking. For backends running on the Docker host, use `127.0.0.1:PORT` when the service is bound to host loopback.
 
-For HTTP on port `80`, update the HTTP services in `config/dynamic/tcp-services.yml` to match the local backend ports that handle redirects and ACME challenge paths.
+For HTTP on port `80`, update the HTTP services in the relevant site file under `config/dynamic/` to match the local backend ports that handle redirects and ACME challenge paths.
 
 ## Known operational risks
 
@@ -58,3 +60,4 @@ For HTTP on port `80`, update the HTTP services in `config/dynamic/tcp-services.
 - Backend certificates and renewal jobs must be monitored on each backend.
 - SNI routing depends on clients sending the expected hostname during the TLS handshake. Clients that connect by IP address or omit SNI will not match hostname-specific routers.
 - Public port `80/tcp` forwards all HTTP paths for configured hostnames to the matching backend.
+- TCP health checks verify reachability, not certificate validity or application-level correctness.

docs/runbook.md

@@ -16,7 +16,7 @@ docker compose down
 
 ### Update backend targets
 
-1. Edit `config/dynamic/tcp-services.yml`.
+1. Edit the relevant site file under `config/dynamic/`.
 2. Run `docker compose config` to catch Compose-level errors.
 3. Watch Traefik logs:
 
@@ -39,6 +39,17 @@ docker compose logs traefik
 
 Confirm that `config/traefik.yml` is mounted and that the ping entrypoint is enabled.
 
+### Backend is unhealthy
+
+Check Traefik logs and verify that the local backend ports respond from the host:
+
+```bash
+curl -H 'Host: lab.younerd.org' http://127.0.0.1:8080/
+openssl s_client -connect 127.0.0.1:8443 -servername lab.younerd.org
+```
+
+Repeat with the hostname and ports from the relevant file under `config/dynamic/`.
+
 ### Clients cannot connect
 
 Check that the host is listening on `80/tcp` and `443/tcp`, firewall rules allow inbound traffic, and backend IP addresses are reachable from Traefik. For services bound to host loopback, configure backends as `127.0.0.1:PORT`.
@@ -49,7 +60,7 @@ Check that port `80/tcp` is reachable from the internet and that the matching HT
 
 ### Wrong certificate is presented
 
-Because TLS is passed through, the certificate comes from the selected backend. Check backend certificate configuration and SNI routing rules in `config/dynamic/tcp-services.yml`.
+Because TLS is passed through, the certificate comes from the selected backend. Check backend certificate configuration and SNI routing rules in the relevant file under `config/dynamic/`.
 
 ## Rollback
 

docs/testing.md

@@ -40,5 +40,6 @@ openssl s_client -connect LOAD_BALANCER_HOST:443 -servername www.azionelab.org
 
 - Docker/Compose validation: `docker compose config`.
 - Runtime health: `docker compose ps`.
+- Backend health checks: Traefik load-balancer health checks configured per site.
 - HTTP route smoke test: `curl`.
 - TLS passthrough smoke test: `openssl s_client`.