From c63045ce71dd59cf2b9a003d6b697ab051a055d8 Mon Sep 17 00:00:00 2001
From: Roberto Alsina <roberto.alsina@gmail.com>
Date: Fri, 3 Oct 2025 12:29:22 -0300
Subject: [PATCH] Add CLAUDE.md documentation for future development

- Document Docker architecture and multi-stage build process
- Include deployment commands and Tailscale management procedures
- Specify rate limiting configuration and service addition process
- Document GoAccess metrics dashboard setup and authentication
- Capture critical deployment requirements for Fly.io compatibility

Co-Authored-By: z.ai LGM 4.5 <noreply@z.ai>
---
 reverse_proxy/CLAUDE.md | 86 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 reverse_proxy/CLAUDE.md

diff --git a/reverse_proxy/CLAUDE.md b/reverse_proxy/CLAUDE.md
new file mode 100644
index 0000000..2bba9e3
--- /dev/null
+++ b/reverse_proxy/CLAUDE.md
@@ -0,0 +1,86 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a nginx reverse proxy running on Fly.io that uses Tailscale to route traffic to internal servers. It provides:
+- HTTPS termination and routing for multiple subdomains
+- Rate limiting and bot protection
+- Real-time traffic metrics via GoAccess
+- Access to internal Tailscale network services
+
+## Architecture
+
+The solution uses a multi-stage Docker build:
+- **Stage 1 (builder)**: Builds any application code (currently minimal)
+- **Stage 2 (tailscale)**: Downloads and extracts Tailscale binaries
+- **Stage 3 (production)**: Final Alpine image with nginx, Tailscale, and GoAccess
+
+### Key Components
+
+- **nginx.conf**: Main configuration with rate limiting zones, server blocks for each subdomain, and GoAccess metrics endpoint
+- **start.sh**: Container startup script that initializes Tailscale, starts GoAccess, and launches nginx
+- **goaccess.sh**: GoAccess dashboard setup with real-time WebSocket support
+- **.htpasswd**: Password protection for metrics dashboard
+
+## Common Commands
+
+### Deployment
+```bash
+fly deploy                    # Deploy to Fly.io
+fly secrets set TAILSCALE_AUTHKEY=<key>  # Set/renew Tailscale auth (expires every 90 days)
+fly certs create <hostname>   # Add SSL certificate for new hostname
+```
+
+### Local Development
+```bash
+docker build -t reverse-proxy .    # Build Docker image
+docker run -p 8080:8080 reverse-proxy  # Run locally (requires TAILSCALE_AUTHKEY env var)
+```
+
+### Tailscale Management
+- Create reusable auth keys at: https://login.tailscale.com/admin/settings/keys
+- Auth keys expire every 90 days and must be renewed
+
+## Adding New Services
+
+1. Add new server block in `nginx.conf`:
+```nginx
+server {
+    listen 0.0.0.0:8080;
+    listen [::]:8080;
+    server_name new-service.ralsina.me;
+
+    location / {
+        limit_req zone=global burst=20 nodelay;
+        proxy_pass http://internal-host:port;
+        proxy_set_header X-Forwarded-Host $http_host;
+    }
+}
+```
+
+2. Create SSL certificate: `flyctl certs create new-service.ralsina.me`
+
+## Rate Limiting Configuration
+
+- **global**: 10r/s (all requests)
+- **post_requests**: 3r/s (POST/PUT/DELETE)
+- **api_services**: 5r/s (API endpoints)
+- **unknown_ua**: 2r/s (bots/crawlers)
+
+Rate limits are applied per zone and configured for low-traffic scenarios (< 12 users).
+
+## Metrics Dashboard
+
+- Access: https://metrics.ralsina.me
+- Authentication: username `metrics`, password stored in `.htpasswd`
+- Real-time updates via WebSocket
+- Logs location: `/var/log/nginx/access.log`
+
+## Important Notes
+
+- All server blocks must listen on `0.0.0.0:8080` for Fly.io compatibility
+- Use `[::]:8080` for IPv6 support
+- Container exposes port 8080 only (external 443→8080 handled by Fly.io)
+- Tailscale hostname is set to `reverseproxy` in the Tailscale network
\ No newline at end of file