Caddy module to require at-proto authentication and restrict routes to DIDs
docs: add compression best practices
author
Will Garrison
date
(Mar 8, 2026, 12:18 AM -0800)
commit
2abcabc7
2abcabc713e7d65ebff708f6b1fbf14dc9f16277
parent
6325c1aa
6325c1aa83bb8b4f917d6064726131dd0b3ba7d4
+17
-18
+17
-18
README.md
+17
-18
README.md
···
114
114
}
115
115
```
116
116
117
-
### Composition: "Standalone Mode"
117
+
## Production Best Practices
118
+
119
+
### Enable Compression
118
120
119
-
To act as a self-contained Authentication Server and Gate in one route, simply compose both directives.
121
+
To ensure the Login and Forbidden HTML pages (which include inline CSS and SVGs) are delivered as quickly as possible, enable Gzip and Zstd compression in your Caddyfile. This reduces the transfer size significantly.
120
122
121
123
```caddyfile
122
124
app.example.com {
123
-
route {
124
-
atproto_portal {
125
-
domain app.example.com
126
-
# Optional: move auth paths to /auth/...
127
-
path_prefix /auth
128
-
}
125
+
# Enable compression for all responses (including auth pages)
126
+
encode zstd gzip
129
127
130
-
atproto_gate {
131
-
# Redirect to local portal (respecting prefix)
132
-
portal_url /auth
133
-
134
-
# Enable refresh
135
-
client_id https://app.example.com/.well-known/oauth-client-metadata.json
136
-
137
-
allow @alice.bsky.social
138
-
}
139
-
128
+
route {
129
+
atproto_portal { ... }
130
+
atproto_gate { ... }
140
131
reverse_proxy localhost:8080
141
132
}
142
133
}
143
134
```
135
+
136
+
### Localhost Development
137
+
138
+
The AT Protocol OAuth flow requires the Authentication Server (PDS) to fetch client metadata from your application. If you are running Caddy on `localhost`:
139
+
140
+
1. **Issue**: Production PDS instances (like `bsky.social`) **cannot reach** `http://localhost`.
141
+
2. **Symptom**: You will see an `invalid_client` error during login.
142
+
3. **Fix**: Expose your local server to the internet using a tunnel (e.g., `ngrok`, `cloudflared`, or `tailscale funnel`) and set your `domain` config to that public URL.
144
143
145
144
## Documentation
146
145