Nginx Reverse Proxy Builder · Python / FastAPI

Nginx Reverse Proxy Config for FastAPI + Uvicorn (SSL, Docs & Timeouts)

Generate an Nginx reverse proxy server block for Python / FastAPI with URL prefix rewrite previews, Certbot SSL redirects, WebSocket upgrade headers, and Docker DNS checks.

Written & verified by Chathura Prabashana · Updated November 2026

1. Adjust stack settings or load a test scenario2. Inspect live diagnostics3. Copy generated config
Quick-Test Scenarios:

1. Domain, Routing & Upstream

2. TLS, WebSockets & Directives

# /etc/nginx/sites-available/api.example.com.conf
# Generated by OpsCheck DevTools — Validate with: sudo nginx -t && sudo systemctl reload nginx

# Required in http {} context (or top of sites-available file) for clean WebSocket upgrades
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    listen [::]:80;
    server_name api.example.com;

    # Redirect all plaintext HTTP traffic permanently to HTTPS
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name api.example.com;

    # Let's Encrypt Certbot TLS Certificates
    ssl_certificate     /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    client_max_body_size 50M;

    # Gzip compression for JSON, JS, CSS, and SVG responses
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 5;
    gzip_min_length 1024;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml image/svg+xml;

    # Baseline HTTP Security Headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        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_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;

        # WebSocket & Upgrade support (requires map $http_upgrade $connection_upgrade)
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_cache_bypass $http_upgrade;

        proxy_connect_timeout 15s;
        proxy_send_timeout 120s;
        proxy_read_timeout 120s;
    }
}
$sudo nginx -t && sudo systemctl reload nginx
URL Routing TransformationPrefix Preserved
GET https://api.example.com/usershttp://127.0.0.1:8000/users

Root location '/' forwards '/users' unchanged to upstream http://127.0.0.1:8000/users.

Configuration Diagnostics

  • infoRoot Proxy Path (/) Preserves Full Request URI

    GET https://api.example.com/users -> Upstream receives http://127.0.0.1:8000/users. Root location '/' forwards '/users' unchanged to upstream http://127.0.0.1:8000/users.

  • passWebSocket Upgrade & Extended Timeout (120s) Enabled

    Configured HTTP/1.1 Upgrade, Connection $connection_upgrade map, and extended proxy_read_timeout for persistent real-time sockets.

  • infoSingle-Layer CORS Policy Reminder

    This configuration intentionally omits Access-Control-Allow-Origin headers so your upstream backend framework (Laravel, FastAPI, Express, ASP.NET Core) owns CORS cleanly without duplicate header rejections.

Runs locally in your browser. Domain names and upstream topology are never sent to a server.

Common Nginx Error Log Pattern (Python / FastAPI)

When upstream sockets, timeouts, body limits, or Docker DNS rules are misconfigured for Python / FastAPI, Nginx typically records an entry matching the log line below inside /var/log/nginx/error.log:

/var/log/nginx/error.log

2026/11/22 15:09:44 [error] 2210#2210: *408 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 198.51.100.14, server: api.example.com, request: "POST /api/v1/embeddings HTTP/2.0", upstream: "http://127.0.0.1:8000/api/v1/embeddings", host: "api.example.com"

Reverse Proxy Architecture & Header Forwarding for Python / FastAPI

FastAPI powered by Uvicorn (or Gunicorn with UvicornWorker processes) is intentionally designed to run behind a battle-tested reverse proxy like Nginx in production. While Uvicorn excels at asynchronous ASGI concurrency, Nginx handles TLS termination, HTTP/2 multiplexing, slow-client buffering, request size limits, and graceful reloads without starving Python worker processes.

Two FastAPI-specific behaviors frequently break behind an unconfigured Nginx proxy: Swagger UI (/docs) subpath resolution and HTTP-to-HTTPS scheme awareness. When Nginx terminates HTTPS on port 443 and forwards plain HTTP to 127.0.0.1:8000, FastAPI generates redirect URLs (such as 307 trailing-slash redirects or OAuth callback links) starting with http:// instead of https:// unless Uvicorn is launched with --proxy-headers and --forwarded-allow-ips and Nginx sends X-Forwarded-Proto $scheme.

If you mount FastAPI under a subpath such as /api/ using Strip Prefix (proxy_pass http://127.0.0.1:8000/;), Swagger UI at /api/docs attempts to download /openapi.json from the domain root instead of /api/openapi.json, returning HTTP 404, unless you also pass --root-path /api (or root_path="/api" in FastAPI()). Furthermore, ML inference, PDF generation, and LLM streaming routes regularly exceed Nginx's default 60-second proxy_read_timeout, throwing 504 Gateway Timeout even while Uvicorn finishes computing cleanly.

Validating your Nginx configuration alongside Uvicorn startup flags prevents silent IP spoofing in rate limiters (where request.client.host reports 127.0.0.1 for every user), ensures multipart file uploads up to 50 MB do not fail with 413 Request Entity Too Large, and keeps WebSocket and Server-Sent Events endpoints responsive under heavy concurrent traffic.

When scaling FastAPI behind Nginx in high-throughput production workloads, tune proxy_connect_timeout, keepalive connections, and client_max_body_size carefully to match your largest file upload or batch embedding endpoint. Monitoring Nginx $upstream_response_time alongside FastAPI structured logs immediately distinguishes slow Python database or vector queries from network saturation. Always verify that /docs, /redoc, and /openapi.json respect your root_path setting; or restrict /docs by internal IP allowlists in Nginx when deploying private B2B FastAPI microservices.

Step-by-Step Nginx & Python / FastAPI Deployment Guide

Apply the Nginx server block above alongside these upstream framework trust-proxy settings so HTTPS detection, real client IPs, and reload safety work reliably in production.

  1. 1Launch Uvicorn/Gunicorn With --proxy-headers and Explicit Trusted Proxy IPs

    /etc/systemd/system/fastapi.service

    Uvicorn ignores X-Forwarded-For and X-Forwarded-Proto headers from Nginx unless --proxy-headers is enabled and Nginx's IP (127.0.0.1 on the same host, or your Docker bridge subnet) is listed in --forwarded-allow-ips.

    /etc/systemd/system/fastapi.serviceini
    [Unit]
    Description=FastAPI Uvicorn Production Service
    After=network.target
    
    [Service]
    User=www-data
    WorkingDirectory=/srv/fastapi-app
    ExecStart=/srv/fastapi-app/.venv/bin/gunicorn app.main:app \
      --workers 4 \
      --worker-class uvicorn.workers.UvicornWorker \
      --bind 127.0.0.1:8000 \
      --forwarded-allow-ips="127.0.0.1"
    Restart=always
    
    [Install]
    WantedBy=multi-user.target
  2. 2Configure FastAPI root_path When Stripping an /api/ Prefix in Nginx

    app/main.py

    If Nginx routes /api/ to FastAPI with Strip Prefix enabled, configure root_path from an environment variable so OpenAPI (/api/docs) and Swagger's Try-It-Out buttons resolve /api/openapi.json accurately.

    app/main.pypython
    import os
    from fastapi import FastAPI, Request
    
    app = FastAPI(
        title="Production FastAPI Service",
        root_path=os.getenv("FASTAPI_ROOT_PATH", ""),
    )
    
    @app.get("/health")
    async def health(request: Request):
        return {
            "status": "ok",
            "scheme": request.url.scheme,
            "client_ip": request.client.host if request.client else None,
        }
  3. 3Disable Nginx Buffering on FastAPI StreamingResponse / SSE Endpoints

    app/routers/stream.py

    Rather than disabling Nginx proxy_buffering globally (which hurts regular JSON throughput), emit the X-Accel-Buffering: no response header directly from FastAPI StreamingResponse endpoints so LLM tokens flush immediately.

    app/routers/stream.pypython
    from fastapi import APIRouter
    from fastapi.responses import StreamingResponse
    
    router = APIRouter()
    
    async def token_generator():
        for chunk in ["hello ", "from ", "fastapi"]:
            yield f"data: {chunk}\n\n"
    
    @router.get("/stream")
    async def stream_events():
        return StreamingResponse(
            token_generator(),
            media_type="text/event-stream",
            headers={"X-Accel-Buffering": "no", "Cache-Control": "no-cache"},
        )
  4. 4Install Nginx Site Config, Test Syntax, and Verify Forwarded Scheme

    terminal

    Enable your generated Nginx server block, reload without dropping active connections, and confirm /health reports scheme: https and your true remote IP.

    terminalbash
    sudo nginx -t && sudo systemctl reload nginx
    curl -s https://api.example.com/health | jq .

Common Python / FastAPI Nginx Reverse Proxy Pitfalls

Review these three production failure modes before reloading Nginx on staging or live servers.

Pitfall 1

Mixed-Content Redirect Loops From Missing --proxy-headers in Uvicorn

Without --proxy-headers and --forwarded-allow-ips, Uvicorn assumes every proxied request arrived over plain HTTP. FastAPI's automatic trailing-slash redirects then emit Location: http://api.example.com/items/ instead of https://, causing browser mixed-content blocks or infinite redirect loops.

Pitfall 2

504 Gateway Timeout on Slow ML or LLM Endpoints

Nginx's default proxy_read_timeout is 60 seconds. Any synchronous FastAPI endpoint or slow upstream inference call taking 65 seconds gets terminated by Nginx with HTTP 504 even though Uvicorn is still running cleanly. Raise proxy_read_timeout to 120s–300s for heavy compute routes.

Pitfall 3

Using --forwarded-allow-ips="*" While Port 8000 Is Publicly Exposed

Setting --forwarded-allow-ips="*" tells Uvicorn to trust X-Forwarded-For from any client. If Uvicorn is bound to 0.0.0.0:8000 without firewall isolation, attackers can spoof X-Forwarded-For headers directly to bypass IP rate limiting. Always bind to 127.0.0.1 or lock down the Docker network.

Related Tools

Pair this Nginx reverse proxy block with healthcheck-gated Docker Compose orchestration and verified browser CORS headers:

Frequently Asked Questions

Why does FastAPI /docs show "Failed to load API definition" (404 /openapi.json) behind Nginx /api/?
When Nginx proxies location /api/ with a trailing slash (proxy_pass http://127.0.0.1:8000/;), FastAPI sees /docs instead of /api/docs and tells Swagger UI to fetch /openapi.json at the domain root. Pass root_path="/api" to FastAPI() or --root-path /api to Uvicorn to fix it immediately.
Should I run multiple Uvicorn workers behind Nginx?
Yes. Run Uvicorn with --workers $(nproc) (or Gunicorn with UvicornWorker) on multi-core servers so Python utilizes every CPU core, while Nginx distributes incoming TLS connections cleanly over loopback HTTP/1.1.
Why does request.client.host always return 127.0.0.1 in FastAPI?
Nginx connects to Uvicorn over 127.0.0.1. Unless Nginx sets X-Forwarded-For $proxy_add_x_forwarded_for AND Uvicorn runs with --proxy-headers --forwarded-allow-ips="127.0.0.1", Uvicorn ignores the forwarded client IP header.
Can Nginx handle both FastAPI HTTP endpoints and FastAPI WebSockets on the same port?
Yes. Enabling WebSocket Upgrade headers (Upgrade $http_upgrade and Connection $connection_upgrade) alongside proxy_http_version 1.1 lets Nginx cleanly proxy standard REST requests and @app.websocket("/ws") connections to Uvicorn port 8000.
Browse all 10 Nginx guides →