| name | reverse-proxy |
| description | Use when working with Nginx, Traefik, or HAProxy — setup, config debugging, SSL termination, routing |
Reverse Proxy
Mode Detection
- Repo mode — templates in
tooling/network/. Scaffold or modify proxy configs.
- Chat mode — user pastes config or error. Diagnose and provide corrected config.
Nginx
Test and reload config (never restart)
nginx -t
nginx -s reload
systemctl reload nginx
Basic reverse proxy config
server {
listen 80;
server_name example.com;
location / {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
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_cache_bypass $http_upgrade;
}
}
SSL with Let's Encrypt
certbot --nginx -d example.com
certbot renew --dry-run
Debugging common errors
| Error | First check |
|---|
| 502 Bad Gateway | Is the upstream running? curl localhost:3000 |
| 504 Gateway Timeout | Increase proxy_read_timeout and proxy_connect_timeout |
| 413 Request Too Large | Increase client_max_body_size |
| SSL handshake error | Check cert validity, check ssl_protocols |
connect() failed (111: Connection refused) | Wrong upstream port or service not running |
Useful debug commands
tail -f /var/log/nginx/error.log
tail -f /var/log/nginx/access.log
nginx -T
Traefik
Dynamic config check
Common issues
| Issue | Fix |
|---|
| Router not matching | Check rule syntax — Host, Path, PathPrefix |
| TLS not working | Check certResolver name matches static config |
| Service unreachable | Check loadBalancer.servers[].url format |
HAProxy
Test and reload config
haproxy -c -f /etc/haproxy/haproxy.cfg
systemctl reload haproxy
Tooling Templates
tooling/network/nginx/ — nginx.conf templates, reverse proxy configs
tooling/network/traefik/ — traefik.yml, dynamic configs
tooling/network/haproxy/ — haproxy.cfg templates
tooling/network/starters/ — full reverse proxy + SSL setups