haproxy-manager-base/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Testing

• API Testing: ./scripts/test-api.sh - Tests all API endpoints with optional authentication
• Certificate Request Testing: ./scripts/test-certificate-request.sh - Tests certificate generation endpoints
• Manual Testing: Run curl commands against http://localhost:8000 endpoints as shown in README.md

Running the Application

• Docker Build: docker build -t haproxy-manager .
• Local Development: python haproxy_manager.py (requires HAProxy, certbot, and dependencies installed)
• Container Run: See README.md for various docker run configurations

Monitoring and Debugging

• Error Monitoring: ./scripts/monitor-errors.sh - Monitor application error logs
• External Monitoring: ./scripts/monitor-errors-external.sh - External monitoring script
• Health Check: curl http://localhost:8000/health
• Log Files:
  • /var/log/haproxy-manager.log - General application logs
  • /var/log/haproxy-manager-errors.log - Error logs for alerting

Architecture Overview

Core Components

1. haproxy_manager.py - Main Flask application providing:

   • RESTful API for HAProxy configuration management
   • SQLite database integration for domain/backend storage
   • Let's Encrypt certificate automation
   • HAProxy configuration generation from Jinja2 templates
   • Optional API key authentication via HAPROXY_API_KEY environment variable

2. Database Schema - SQLite database with three main tables:

   • domains - Domain configurations with SSL settings
   • backends - Backend service definitions linked to domains
   • backend_servers - Individual servers within backend groups

3. Template System - Jinja2 templates for HAProxy configuration generation:

   • hap_header.tpl - Global HAProxy settings, defaults, and HTTP/2 tuning
   • hap_backend.tpl - Backend server definitions
   • hap_listener.tpl - Frontend listener configurations with rate limiting
   • hap_letsencrypt.tpl - SSL certificate configurations
   • hap_security_tables.tpl - Stats frontend and security stick tables
   • Template override support for custom backend configurations

4. Certificate Management - Automated SSL certificate handling:

   • Let's Encrypt integration with certbot
   • Self-signed certificate fallback for development
   • Certificate renewal automation via cron
   • Certificate download endpoints for external services

Configuration Flow

1. Domain added via /api/domain endpoint → Database updated
2. generate_config() function → Reads database, renders Jinja2 templates → Writes /etc/haproxy/haproxy.cfg
3. HAProxy reload via socket API (/tmp/haproxy-cli) or process restart
4. SSL certificate generation via Let's Encrypt or self-signed fallback

Key Design Patterns

• Template-driven configuration: HAProxy config generated from modular Jinja2 templates
• Database-backed state: All configuration persisted in SQLite for reliability
• API-first design: All operations exposed via REST endpoints
• Process monitoring: Health checks and automatic HAProxy restart capabilities
• Comprehensive logging: Operation logging with error alerting support

Authentication & Security

• Optional API key authentication controlled by HAPROXY_API_KEY environment variable
• All API endpoints (except /health and /) require Bearer token when API key is set
• Certificate private keys combined with certificates in HAProxy-compatible format
• Default backend page for unmatched domains instead of exposing HAProxy errors

Rate Limiting & Connection Limits (hap_listener.tpl)

• Stick table: type ip size 200k expire 10m tracking conn_cur, conn_rate(10s), http_req_rate(10s), http_err_rate(30s)
• Tracks real client IP via var(txn.real_ip) to work correctly behind Cloudflare/proxies
• Rate limit thresholds:
  • Tarpit at 3000 req/10s (300 req/s)
  • Hard block (deny) at 5000 req/10s (500 req/s)
  • Connection rate limit: 500/10s
  • Concurrent connection limit: 500
  • Error rate limit: 100/30s
• Whitelist bypasses (exempt from rate limits):
  • is_local — RFC1918 private address ranges
  • is_trusted_ip — source IPs listed in trusted_ips.list
  • is_whitelisted — real IPs (from proxy headers) matched in trusted_ips.map

Trusted IP Whitelist Files

• trusted_ips.list — Source IP whitelist for rate limit bypass (one CIDR/IP per line)
• trusted_ips.map — Real IP whitelist for proxy-header matching (format: <IP> 1)
• Both files are baked into the Docker image via COPY in the Dockerfile
• Currently contains phone system IP 172.116.197.166

Timeout Hardening (hap_header.tpl)

• timeout http-request: 300s -> 30s (slowloris protection)
• timeout connect: 120s -> 10s
• timeout client: 10m -> 5m
• timeout http-keep-alive: 120s -> 30s

HTTP/2 Protection (hap_header.tpl)

• tune.h2.fe.max-total-streams 2000 — limits total streams per HTTP/2 connection
• tune.h2.fe.glitches-threshold 50 — CVE-2023-44487 Rapid Reset protection

Stats Frontend (hap_security_tables.tpl)

• HAProxy stats page bound to 127.0.0.1:8404 (localhost only, accessible inside container)
• Template: templates/hap_security_tables.tpl

Deployment Context

• Designed to run as Docker container with persistent volumes for certificates and configurations
• Exposes ports 80 (HTTP), 443 (HTTPS), and 8000 (management API/UI)
• Stats page on port 8404 (localhost only inside container)
• Management interface on port 8000 should be firewall-protected in production
• Dockerfile HEALTHCHECK verifies both port 8000 (Flask API) and port 80 (HAProxy), with start-period=60s and timeout=10s
• Supports deployment on servers with git directory at /root/whp and web file sync via rsync to /docker/whp/web/
• HAProxy is version 3.0.11