Roberto Alsina
c63045ce71
- 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>
86 lines
2.8 KiB
Markdown
86 lines
2.8 KiB
Markdown
# 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 |