working on caddy sidecar

README.md

@@ -77,17 +77,42 @@ abra app run YOURAPPDOMAIN app -- \
 
 User handles on a PDS can work in two ways:
 
-1. **Subdomain handles** (e.g. `user.pds.example.com`): Requires a wildcard DNS
-   record (`*.pds.example.com`) pointing to your server, and wildcard TLS
-   certificates (which require DNS challenge configuration in Traefik).
+1. **Subdomain handles** (e.g. `user.pds.example.com`): The default. Requires a
+   wildcard DNS record (`*.pds.example.com`) pointing to your server. TLS is
+   handled automatically by the Caddy sidecar (see below).
 
 2. **Domain handles** (e.g. `user.com`): Users can use their own domain as a
    handle by adding a DNS TXT record at `_atproto.user.com` with the value
    `did=did:plc:<their-did>`. This works without any additional server
    configuration.
 
-Domain handles are recommended for most deployments as they don't require
-wildcard TLS configuration.
+## TLS architecture (Caddy sidecar)
+
+This recipe uses a **Caddy sidecar** for TLS instead of letting Traefik terminate
+TLS directly. This is needed because Bluesky subdomain handles require TLS
+certificates for each `user.pds.example.com` subdomain, and Traefik cannot issue
+on-demand per-subdomain certificates.
+
+The architecture:
+
+1. **Traefik** receives TLS connections on port 443 and does **TCP passthrough**
+   (no TLS termination) for traffic matching `DOMAIN` and `*.DOMAIN`, forwarding
+   the raw TLS stream to Caddy.
+2. **Caddy** terminates TLS using **on-demand certificates** — it automatically
+   obtains a Let's Encrypt certificate for each subdomain the first time a
+   connection arrives, using the TLS-ALPN-01 challenge.
+3. **Caddy** reverse proxies the decrypted HTTP traffic to the PDS on port 3000.
+
+This matches how the [upstream PDS](https://github.com/bluesky-social/pds) is
+designed to work (it ships with Caddy), adapted for Co-op Cloud's Traefik-based
+routing. The PDS exposes a `/tls-check` endpoint that Caddy consults before
+issuing a certificate, preventing abuse.
+
+**Note:** The first request to a new subdomain handle may take 10-30 seconds while
+Caddy obtains the TLS certificate from Let's Encrypt. Subsequent requests are instant.
+
+No changes to the Traefik recipe are needed — the TCP passthrough is configured
+entirely via deploy labels on the Caddy service in this recipe's `compose.yml`.
 
 ## DNS setup