feat: enhance client IP resolution

Author: MoKhajavi75

CLAUDE.md

@@ -48,4 +48,6 @@ The entire backend is in `main.go`. Web assets (`web/index.html`, `web/script.js
 
 **Versioning:** The version string is injected at build time via `-ldflags "-X main.Version=$(VERSION)"` and exposed via `/api/version`. The Docker image receives it via the `VERSION` build arg.
 
-**Docker:** A multi-stage `Dockerfile` uses `ARG GO_VERSION` and `ARG ALPINE_VERSION` to parameterise the base images (`golang:${GO_VERSION}-alpine` / `alpine:${ALPINE_VERSION}`). The canonical values live in the top-level `env:` block of `release.yml` (`GO_VERSION`, `ALPINE_VERSION`) and are passed as build args by the workflow — one place to bump either version. Build locally: `docker build --build-arg VERSION=x.y.z -t local-clipboard .`. Run: `docker run -p 8080:8080 local-clipboard`.
+**Client IP resolution:** The `realIP` helper in `main.go` resolves the real client IP by checking `X-Forwarded-For` (first entry in the comma-separated list) then `X-Real-IP`, falling back to `r.RemoteAddr`. This is necessary when running behind a reverse proxy or Docker, where NAT would otherwise cause all clients to appear as the bridge gateway IP (e.g. `172.18.0.1`). The WebSocket handler uses `realIP(r)` when registering each connection.
+
+**Docker:** A multi-stage `Dockerfile` uses `ARG GO_VERSION` and `ARG ALPINE_VERSION` to parameterise the base images (`golang:${GO_VERSION}-alpine` / `alpine:${ALPINE_VERSION}`). The canonical values live in the top-level `env:` block of `release.yml` (`GO_VERSION`, `ALPINE_VERSION`) and are passed as build args by the workflow — one place to bump either version. Build locally: `docker build --build-arg VERSION=x.y.z -t local-clipboard .`. Run: `docker run -p 8080:8080 local-clipboard`. When running via Docker Compose behind a reverse proxy, configure the proxy to set `X-Forwarded-For` or `X-Real-IP` so client IPs are preserved correctly.

README.md

@@ -111,4 +111,49 @@ go mod vendor
 
 This will download all dependencies into a `vendor/` directory for offline use.
 
+## Docker
+
+### Run with Docker
+
+```bash
+docker run -p 8080:8080 ghcr.io/mokhajavi75/local-clipboard:latest
+```
+
+### Run with Docker Compose
+
+```yaml
+services:
+  local-clipboard:
+    image: ghcr.io/mokhajavi75/local-clipboard:latest
+    restart: unless-stopped
+    ports:
+      - "8080:8080"
+```
+
+### Behind a Reverse Proxy
+
+When running behind a reverse proxy, configure it to forward the real client IP so sender labels show correctly instead of the Docker gateway IP.
+
+**Caddy:**
+
+```caddy
+example.com {
+  reverse_proxy 127.0.0.1:8080 {
+    header_up X-Real-IP {remote_host}
+  }
+}
+```
+
+> Caddy sets `X-Forwarded-For` automatically; the `header_up` line adds `X-Real-IP` as well.
+
+**nginx:**
+
+```nginx
+location / {
+  proxy_pass http://127.0.0.1:8080;
+  proxy_set_header X-Forwarded-For $remote_addr;
+  proxy_set_header X-Real-IP       $remote_addr;
+}
+```
+
 Enjoy your local clipboard! 🎉

main.go

@@ -11,6 +11,7 @@ import (
 	"net"
 	"net/http"
 	"os"
+	"strings"
 	"sync"
 	"time"
 
@@ -307,7 +308,7 @@ func (h *Hub) handleWebSocket(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	ip, _, _ := net.SplitHostPort(r.RemoteAddr)
+	ip := realIP(r)
 	h.register <- connInfo{conn: conn, ip: ip}
 
 	defer func() {
@@ -333,6 +334,21 @@ func (h *Hub) handleWebSocket(w http.ResponseWriter, r *http.Request) {
 	}
 }
 
+func realIP(r *http.Request) string {
+	if xff := r.Header.Get("X-Forwarded-For"); xff != "" {
+		// X-Forwarded-For can be a comma-separated list; the first entry is the client
+		if i := strings.Index(xff, ","); i != -1 {
+			return strings.TrimSpace(xff[:i])
+		}
+		return strings.TrimSpace(xff)
+	}
+	if xri := r.Header.Get("X-Real-IP"); xri != "" {
+		return strings.TrimSpace(xri)
+	}
+	ip, _, _ := net.SplitHostPort(r.RemoteAddr)
+	return ip
+}
+
 func getLocalIP() string {
 	ifaces, err := net.Interfaces()
 	if err != nil {