Add static site generation with nginx + hardened FastAPI sidecar

Pre-render ~1,277 high-traffic HTML pages (homepage, books, chapters)
at build time and serve them directly via nginx. All other routes
(verses, search, API, PDFs, Strong's) fall through to a FastAPI
sidecar. If the sidecar crashes, nginx continues serving static
pages and health checks.

Also harden the FastAPI app against the memory/crash issues:
- Switch from bare uvicorn to gunicorn with uvicorn workers
- Add --max-requests worker recycling to prevent memory leaks
- Add --timeout to kill hung workers
- Add per-IP rate limiting middleware (10 req/s, burst of 50)
- Add request timeout middleware (30s max per request)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: kennethreitz

Dockerfile

@@ -49,5 +49,9 @@ COPY . .
 # Build search index at image build time for fast searches
 RUN python3 -c "from kjvstudy_org.utils.search_index import init_search_index; init_search_index()"
 
-# Run uvicorn directly (no nginx sidecar)
-CMD ["sh", "-c", "uv run uvicorn kjvstudy_org.server:app --host ${HOST:-0.0.0.0} --port ${PORT:-8000} --workers ${WORKERS:-1} --proxy-headers"]
+# Run with gunicorn + uvicorn workers for production resilience:
+#   --max-requests: recycle workers after N requests (prevents memory leaks)
+#   --max-requests-jitter: stagger recycling so workers don't all restart at once
+#   --timeout: kill workers that hang for >60s
+#   --graceful-timeout: give workers 10s to finish after SIGTERM
+CMD ["sh", "-c", "uv run gunicorn kjvstudy_org.server:app --worker-class uvicorn.workers.UvicornWorker --bind ${HOST:-0.0.0.0}:${PORT:-8000} --workers ${WORKERS:-2} --max-requests 2000 --max-requests-jitter 500 --timeout 60 --graceful-timeout 10 --proxy-protocol --forwarded-allow-ips='*' --access-logfile -"]

Dockerfile.static

@@ -0,0 +1,89 @@
+# =============================================================================
+# Stage 1: Builder — install deps, generate static HTML pages
+# =============================================================================
+FROM python:3.13 AS builder
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy
+
+WORKDIR /app
+
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-install-project --no-dev
+
+COPY . .
+
+# Build search index (needed by app startup)
+RUN uv run python3 -c "from kjvstudy_org.utils.search_index import init_search_index; init_search_index()"
+
+# Generate static HTML pages (~50K files, no PDFs or API JSON)
+RUN uv run python scripts/generate_static_site.py --output /app/dist --workers 4
+
+# =============================================================================
+# Stage 2: Runtime — nginx for static files + FastAPI sidecar for dynamic routes
+# =============================================================================
+FROM python:3.13-slim
+
+# Install nginx + runtime deps for WeasyPrint (PDF generation in sidecar)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    nginx \
+    curl \
+    libpango-1.0-0 \
+    libharfbuzz0b \
+    libpangoft2-1.0-0 \
+    libffi8 \
+    libgdk-pixbuf-2.0-0 \
+    shared-mime-info \
+    fonts-dejavu-core \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONPATH="/app" \
+    PATH="/app/.venv/bin:$PATH"
+
+WORKDIR /app
+
+# Copy virtualenv from builder
+COPY --from=builder /app/.venv /app/.venv
+
+# Copy application code (needed by the sidecar)
+COPY --from=builder /app/kjvstudy_org /app/kjvstudy_org
+COPY --from=builder /app/scripts/search_api.py /app/scripts/search_api.py
+
+# Copy pre-rendered static site
+COPY --from=builder /app/dist /app/dist
+
+# Copy nginx config
+COPY nginx.conf /etc/nginx/nginx.conf
+
+# Entrypoint: start FastAPI sidecar + nginx
+COPY <<'ENTRY' /app/start.sh
+#!/bin/sh
+set -e
+
+# Start the FastAPI sidecar in the background
+# It handles: search, API, PDFs, OG images, and any uncached pages
+python3 /app/scripts/search_api.py &
+SIDECAR_PID=$!
+
+# Wait briefly for sidecar to be ready
+sleep 1
+
+# Start nginx in the foreground
+exec nginx -g 'daemon off;'
+ENTRY
+RUN chmod +x /app/start.sh
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=15s --timeout=5s --start-period=10s \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+CMD ["/app/start.sh"]

fly.toml

@@ -10,6 +10,7 @@ primary_region = 'iad'
 strategy = "bluegreen"
 
 [build]
+dockerfile = "Dockerfile.static"
 
 [http_service]
 internal_port = 8000
@@ -45,5 +46,5 @@ PYTHONDONTWRITEBYTECODE = "1"
 # Lazy-load interlinear data to reduce memory usage
 PRELOAD_INTERLINEAR = "false"
 
-# Number of Uvicorn workers
-WORKERS = "2"
+# Sidecar workers (gunicorn)
+SIDECAR_WORKERS = "1"

kjvstudy_org/server.py

@@ -3,6 +3,7 @@
 import os
 import re
 import random
+import time
 from contextlib import asynccontextmanager
 from datetime import datetime, timedelta
 from pathlib import Path as PathLib
@@ -236,6 +237,70 @@ async def dispatch(self, request: Request, call_next):
         return response
 
 
+# Rate limiting middleware — per-IP request throttle
+class RateLimitMiddleware(BaseHTTPMiddleware):
+    """Simple in-memory per-IP rate limiter using a sliding window."""
+
+    def __init__(self, app, requests_per_second: float = 10.0):
+        super().__init__(app)
+        self.rate = requests_per_second
+        # {ip: (token_count, last_refill_time)}
+        self._buckets: dict[str, tuple[float, float]] = {}
+        self._max_tokens = requests_per_second * 5  # burst allowance
+
+    async def dispatch(self, request: Request, call_next):
+        # Skip rate limiting for health checks
+        if request.url.path == "/health":
+            return await call_next(request)
+
+        ip = request.client.host if request.client else "unknown"
+        now = time.monotonic()
+
+        tokens, last = self._buckets.get(ip, (self._max_tokens, now))
+        elapsed = now - last
+        tokens = min(self._max_tokens, tokens + elapsed * self.rate)
+
+        if tokens < 1.0:
+            return JSONResponse(
+                {"detail": "Too many requests"},
+                status_code=429,
+                headers={"Retry-After": "1"},
+            )
+
+        self._buckets[ip] = (tokens - 1.0, now)
+
+        # Periodic cleanup — evict stale entries every ~1000 requests
+        if len(self._buckets) > 5000:
+            cutoff = now - 60
+            self._buckets = {
+                k: (t, ts) for k, (t, ts) in self._buckets.items() if ts > cutoff
+            }
+
+        return await call_next(request)
+
+
+# Request timeout middleware — kill requests that take too long
+class TimeoutMiddleware(BaseHTTPMiddleware):
+    """Cancel requests that exceed a time limit."""
+
+    def __init__(self, app, timeout_seconds: float = 30.0):
+        super().__init__(app)
+        self.timeout = timeout_seconds
+
+    async def dispatch(self, request: Request, call_next):
+        import asyncio
+        try:
+            return await asyncio.wait_for(
+                call_next(request),
+                timeout=self.timeout,
+            )
+        except asyncio.TimeoutError:
+            return JSONResponse(
+                {"detail": "Request timeout"},
+                status_code=504,
+            )
+
+
 # Add GZip compression middleware (compress responses > 500 bytes)
 app.add_middleware(GZipMiddleware, minimum_size=500)
 
@@ -245,6 +310,12 @@ async def dispatch(self, request: Request, call_next):
 # Add bot logging middleware
 app.add_middleware(BotLoggerMiddleware)
 
+# Add rate limiting (10 req/s per IP, burst of 50)
+app.add_middleware(RateLimitMiddleware, requests_per_second=10.0)
+
+# Add request timeout (30 seconds max, 60 for PDFs handled by route-level timeout)
+app.add_middleware(TimeoutMiddleware, timeout_seconds=30.0)
+
 
 # Set up Jinja2 templates and static files
 current_dir = PathLib(__file__).parent

nginx.conf

@@ -0,0 +1,184 @@
+worker_processes auto;
+error_log /var/log/nginx/error.log warn;
+pid /var/run/nginx.pid;
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+
+    log_format main '$remote_addr - [$time_local] "$request" $status $body_bytes_sent "$http_user_agent"';
+    access_log /var/log/nginx/access.log main;
+
+    sendfile on;
+    keepalive_timeout 65;
+
+    # Gzip
+    gzip on;
+    gzip_vary on;
+    gzip_proxied any;
+    gzip_comp_level 6;
+    gzip_min_length 500;
+    gzip_types text/plain text/css text/xml text/javascript
+               application/json application/javascript application/xml
+               application/rss+xml image/svg+xml;
+
+    # Upstream: FastAPI sidecar for dynamic routes
+    upstream sidecar {
+        server 127.0.0.1:8001;
+    }
+
+    server {
+        listen 8000;
+        server_name _;
+        root /app/dist;
+
+        # Security headers
+        add_header X-Content-Type-Options nosniff always;
+        add_header X-Frame-Options SAMEORIGIN always;
+
+        # -----------------------------------------------------------
+        # Dynamic routes — proxy to FastAPI sidecar
+        # -----------------------------------------------------------
+
+        # Search (dynamic query results)
+        location = /search {
+            proxy_pass http://sidecar;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+
+        # All API endpoints
+        location /api/ {
+            proxy_pass http://sidecar;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+
+        # PDF generation (on-demand)
+        location ~ /pdf$ {
+            proxy_pass http://sidecar;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_read_timeout 30s;
+        }
+
+        # Verse of the day redirect (needs server-side date logic)
+        location = /verse-of-the-day {
+            proxy_pass http://sidecar;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+
+        # OG images (dynamically generated)
+        location /og/ {
+            proxy_pass http://sidecar;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+
+        # Family tree search (dynamic query)
+        location = /family-tree/search {
+            proxy_pass http://sidecar;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+
+        # Family tree SVG (dynamically rendered)
+        location = /family-tree/lineage.svg {
+            proxy_pass http://sidecar;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+
+        # OpenAPI docs
+        location /api/docs {
+            proxy_pass http://sidecar;
+            proxy_set_header Host $host;
+        }
+        location /api/redoc {
+            proxy_pass http://sidecar;
+            proxy_set_header Host $host;
+        }
+        location /api/openapi.json {
+            proxy_pass http://sidecar;
+            proxy_set_header Host $host;
+        }
+
+        # -----------------------------------------------------------
+        # Health check — static (no sidecar dependency)
+        # -----------------------------------------------------------
+        location = /health {
+            default_type application/json;
+            return 200 '{"status":"healthy","service":"kjv-study"}';
+        }
+
+        # -----------------------------------------------------------
+        # Static assets — aggressive caching
+        # -----------------------------------------------------------
+        location /static/ {
+            expires 1y;
+            add_header Cache-Control "public, immutable";
+            try_files $uri =404;
+        }
+
+        # -----------------------------------------------------------
+        # Robots / sitemaps
+        # -----------------------------------------------------------
+        location = /robots.txt {
+            default_type text/plain;
+            expires 1d;
+        }
+        location ~ ^/sitemap.*\.xml$ {
+            default_type application/xml;
+            expires 1d;
+        }
+
+        # Random verse list JSON
+        location = /random-verse-list.json {
+            default_type application/json;
+            expires 7d;
+        }
+
+        # -----------------------------------------------------------
+        # Default — serve pre-rendered HTML with clean URLs
+        # -----------------------------------------------------------
+        location / {
+            try_files $uri $uri/index.html $uri/ @sidecar;
+            expires 7d;
+            add_header Cache-Control "public";
+        }
+
+        # Fallback: if no static file exists, proxy to sidecar
+        location @sidecar {
+            proxy_pass http://sidecar;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+
+        # Custom 404
+        error_page 404 /404.html;
+        location = /404.html {
+            internal;
+        }
+    }
+}