first commit

docs/production.md

@@ -0,0 +1,75 @@
+# Production Guide
+
+## Build
+
+Windows:
+
+```powershell
+$version = "1.0.0"
+$commit = git rev-parse --short HEAD
+$date = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
+
+go generate ./...
+go test ./...
+go build -trimpath -ldflags "-s -w -X ipecho/internal/buildinfo.Version=$version -X ipecho/internal/buildinfo.Commit=$commit -X ipecho/internal/buildinfo.Date=$date" -o bin\ipecho.exe .\cmd\ipecho
+```
+
+Linux:
+
+```bash
+version=1.0.0
+commit="$(git rev-parse --short HEAD)"
+date="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+go generate ./...
+go test ./...
+go build -trimpath -ldflags "-s -w -X ipecho/internal/buildinfo.Version=$version -X ipecho/internal/buildinfo.Commit=$commit -X ipecho/internal/buildinfo.Date=$date" -o bin/ipecho ./cmd/ipecho
+```
+
+`go generate ./...` refreshes:
+
+- `assets/icon.svg`
+- `assets/favicon.svg`
+- `assets/ipecho.ico`
+- `assets/favicon.ico`
+- `internal/httpapi/static/favicon.ico`
+- `cmd/ipecho/rsrc_windows_amd64.syso`
+
+The `.syso` file is used by Go when building `cmd/ipecho` on Windows amd64, so `bin\ipecho.exe` gets the application icon. The HTML does not include a favicon link; browsers request `/favicon.ico` automatically, and the service serves the embedded favicon.
+
+## Configuration
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `ADDR` | `:8080` | TCP address for the Go server. In production behind nginx, use `127.0.0.1:8080`. |
+| `TRUST_PROXY_HEADERS` | `false` | Enables `Forwarded`, `X-Forwarded-For`, and `X-Real-IP` parsing. |
+| `TRUSTED_PROXY_CIDRS` | `127.0.0.1/32,::1/128` | Proxy IP ranges allowed to supply forwarded client IP headers. |
+| `READ_HEADER_TIMEOUT` | `5s` | Time allowed to read request headers. |
+| `READ_TIMEOUT` | `10s` | Time allowed to read the whole request. |
+| `WRITE_TIMEOUT` | `10s` | Time allowed to write the response. |
+| `IDLE_TIMEOUT` | `60s` | Keep-alive idle timeout. |
+| `SHUTDOWN_TIMEOUT` | `5s` | Graceful shutdown deadline after SIGINT/SIGTERM. |
+| `MAX_HEADER_BYTES` | `1048576` | Maximum request header size. |
+| `LOG_LEVEL` | `info` | `debug`, `info`, `warn`, or `error`. |
+| `LOG_FORMAT` | `text` | `text` or `json`. Use `json` for production log collectors. |
+
+Example behind nginx on the same host:
+
+```powershell
+$env:ADDR = "127.0.0.1:8080"
+$env:TRUST_PROXY_HEADERS = "true"
+$env:TRUSTED_PROXY_CIDRS = "127.0.0.1/32,::1/128"
+$env:LOG_FORMAT = "json"
+.\bin\ipecho.exe
+```
+
+Do not enable `TRUST_PROXY_HEADERS` while exposing the Go server directly to the internet. A direct client can spoof those headers.
+
+## Production Checklist
+
+- Run the Go service on loopback or a private network, not directly on a public interface, when proxy headers are trusted.
+- Terminate TLS at nginx or another reverse proxy.
+- Use `LOG_FORMAT=json` in production.
+- Keep `/healthz` available for uptime checks.
+- Build with `-trimpath` and release metadata through `-ldflags`.
+- Regenerate icons with `go generate ./...` after changing `tools/icongen`.