Files

Roberto Alsina c63045ce71 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>

2025-10-03 12:29:22 -03:00

2.8 KiB

Raw Blame History

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

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

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

Add new server block in nginx.conf:

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;
    }
}

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

2.8 KiB Raw Blame History