first commit

docs/nginx.md

@@ -0,0 +1,126 @@
+# nginx Configuration
+
+This service should usually sit behind nginx. Let nginx handle TLS, public ports, compression, and connection buffering. Let the Go app listen on loopback.
+
+## App Environment
+
+Run the app with:
+
+```bash
+ADDR=127.0.0.1:8080
+TRUST_PROXY_HEADERS=true
+TRUSTED_PROXY_CIDRS=127.0.0.1/32,::1/128
+LOG_FORMAT=json
+```
+
+If nginx runs in Docker or on another private host, add that proxy network to `TRUSTED_PROXY_CIDRS`, for example:
+
+```bash
+TRUSTED_PROXY_CIDRS=127.0.0.1/32,::1/128,172.16.0.0/12
+```
+
+## Basic Reverse Proxy
+
+Replace `ip.example.com` with your domain.
+
+```nginx
+upstream ipecho {
+    server 127.0.0.1:8080;
+    keepalive 16;
+}
+
+server {
+    listen 80;
+    server_name ip.example.com;
+
+    location / {
+        proxy_pass http://ipecho;
+        proxy_http_version 1.1;
+
+        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;
+        proxy_set_header X-Forwarded-Host $host;
+
+        proxy_connect_timeout 5s;
+        proxy_send_timeout 15s;
+        proxy_read_timeout 15s;
+    }
+}
+```
+
+## HTTPS Server Block
+
+After installing a certificate, use:
+
+```nginx
+upstream ipecho {
+    server 127.0.0.1:8080;
+    keepalive 16;
+}
+
+server {
+    listen 80;
+    server_name ip.example.com;
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name ip.example.com;
+
+    ssl_certificate /etc/letsencrypt/live/ip.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/ip.example.com/privkey.pem;
+
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+
+    location / {
+        proxy_pass http://ipecho;
+        proxy_http_version 1.1;
+
+        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 https;
+        proxy_set_header X-Forwarded-Host $host;
+
+        proxy_connect_timeout 5s;
+        proxy_send_timeout 15s;
+        proxy_read_timeout 15s;
+    }
+}
+```
+
+## With A CDN Or Load Balancer In Front
+
+If nginx is behind another proxy, configure nginx real IP handling first so `$remote_addr` becomes the actual client address before it is passed to the Go app.
+
+Example shape:
+
+```nginx
+real_ip_header X-Forwarded-For;
+real_ip_recursive on;
+
+# Add only the CIDR ranges for proxies you control or your CDN publishes.
+set_real_ip_from 203.0.113.0/24;
+set_real_ip_from 2001:db8::/32;
+```
+
+Keep those CIDR ranges current. Do not trust `0.0.0.0/0` or `::/0`.
+
+## Verify
+
+```bash
+curl https://ip.example.com/ip
+curl https://ip.example.com/json
+curl -I https://ip.example.com/favicon.ico
+curl http://127.0.0.1:8080/healthz
+```
+
+Expected:
+
+- `/ip` returns the client IP as plain text.
+- `/json` shows `ip`, `remote_addr`, headers, method, and path.
+- `/favicon.ico` returns `Content-Type: image/x-icon`.
+- `/healthz` returns `ok`.