Initial commit

2026-01-08 20:33:45 +02:00
commit 0e9b3e35df
4 changed files with 212 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,69 @@
+# dev-proxy
+
+A local development proxy that intercepts a production domain and routes most traffic to your local dev server while passing through specific API patterns to the real backend.
+
+## Dependencies
+
+### macOS (Homebrew)
+```bash
+brew install nginx mkcert nss bind
+mkcert -install
+```
+
+### Arch Linux (pacman)
+```bash
+sudo pacman -S nginx mkcert nss bind
+mkcert -install
+```
+
+## Usage
+
+```bash
+./dev-proxy.sh <domain> <local-target> "<passthrough-patterns>" [real-ip]
+```
+
+### Parameters
+
+| Parameter | Description | Example |
+|-----------|-------------|---------|
+| `domain` | Production domain to intercept | `example.com` |
+| `local-target` | Local dev server address | `127.0.0.1:3000` |
+| `passthrough-patterns` | Comma-separated URL patterns to forward to real backend | `"api/*,assets/*"` |
+| `real-ip` | (Optional) Override resolved IP for the real backend | `1.2.3.4` |
+
+### Example
+
+```bash
+./dev-proxy.sh myapp.example.com 127.0.0.1:3000 "api/*,auth/*,static/*"
+```
+
+This will:
+1. Add `127.0.0.1 myapp.example.com` to `/etc/hosts`
+2. Generate a trusted SSL certificate using mkcert
+3. Start nginx on port 443
+4. Route `/api/*`, `/auth/*`, `/static/*` to the real `myapp.example.com` backend
+5. Route everything else to your local dev server at `127.0.0.1:3000`
+
+Press `Ctrl+C` to stop. The script automatically cleans up `/etc/hosts` and temporary files on exit.
+
+## How It Works
+
+```
+Browser → nginx (localhost:443) → Local dev server (localhost:3000)
+                                → Real backend (for passthrough patterns)
+```
+
+The proxy:
+- Modifies `/etc/hosts` to point the domain to localhost
+- Uses mkcert for trusted local HTTPS certificates
+- Routes requests based on URL patterns
+- Supports WebSocket connections (for HMR/hot reload)
+- Sets proper SNI headers for the real backend
+
+## Troubleshooting
+
+**Certificate not trusted**: Run `mkcert -install` to install the root CA.
+
+**Port 443 in use**: Stop any existing web servers or other instances of the proxy.
+
+**DNS still resolving to real IP**: Clear DNS cache or wait for TTL to expire. The script uses Google DNS (8.8.8.8) to resolve the real IP before modifying hosts.