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

Memory Optimization

Configured for 256MB Fly.io containers:

Go GC settings: GOGC=10 and GOMEMLIMIT=100MiB for aggressive Tailscale memory management
GoAccess: Static HTML generation (60-second intervals) instead of real-time WebSocket
Nginx: Reduced connection timeouts and buffer sizes
Package optimization: Minimal Alpine packages only

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
Static HTML generation (updates every 60 seconds for memory efficiency)
Logs location: /var/log/nginx/access.log
Note: Real-time WebSocket disabled to reduce memory usage on 256MB containers

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

3.3 KiB Raw Permalink Blame History