MeghdadFadaee/ip-echo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
Meghdad Fadaee
2026-05-13 03:05:24 +03:30
commit 4c7343665a
27 changed files with 2581 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

126
docs/nginx.md Normal file
View File

@@ -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`.

75
docs/production.md Normal file
View File

@@ -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`.