deployment/proxy

12 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Proxy forwarded headers in FastAPI

A proxy in front of a FastAPI application sets forwarded headers before sending requests to the server to indicate the request was forwarded by the proxy. These headers preserve the original public URL, protocol (HTTPS), and domain. The server program (such as Uvicorn via FastAPI CLI) can interpret these headers and pass that information to the application.

HTTP proxy forwarded header names

The three proxy forwarded headers are: X-Forwarded-For (the original client's IP address), X-Forwarded-Proto (the original protocol, such as https), and X-Forwarded-Host (the original host domain).

Security consideration for proxy headers

For security reasons, the server does not interpret forwarded headers by default because it does not know if it is behind a trusted proxy. Headers must be explicitly trusted by configuration.

FastAPI CLI option --forwarded-allow-ips

The FastAPI CLI option --forwarded-allow-ips configures which IP addresses should be trusted to provide forwarded headers. Setting --forwarded-allow-ips="*" trusts all incoming IPs. When set, FastAPI will interpret X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Host headers and use them to generate correct URLs in redirects.

root_path for proxy with stripped path prefix

The root_path is an ASGI specification mechanism provided by FastAPI (through Starlette) to handle proxies that add a path prefix. When a proxy strips a path prefix before forwarding to the application, root_path ensures the application and its documentation (OpenAPI schema, docs UI) function correctly with the prefix.

Provide root_path via FastAPI CLI --root-path

Use the FastAPI CLI command line option --root-path to set the root path. Example: uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1. This is equivalent to passing the root_path to Uvicorn or Hypercorn.

Set root_path in FastAPI app constructor

Alternatively to using the --root-path CLI option, you can set the root_path parameter when creating the FastAPI app instance: app = FastAPI(root_path="/api/v1"). This is equivalent to passing --root-path to the command line.

Access root_path in request scope

The current root_path is available in the ASGI scope dictionary for each request. You can access it from the request scope to determine the root path being used by the application.

Uvicorn does not enforce root_path path matching

The Uvicorn server does not use root_path to enforce path matching. It expects requests at the actual application path (e.g., http://127.0.0.1:8000/app). The proxy is responsible for adding the path prefix on top. The root_path is only passed to the application for its use.

OpenAPI servers list with root_path

When root_path is set, FastAPI automatically inserts a server entry with the root_path URL at the beginning of the servers list in the OpenAPI schema. If custom servers are provided and root_path exists, FastAPI adds the root_path server first. This can be disabled with root_path_in_servers=False.

Disable automatic server generation from root_path

Set the parameter root_path_in_servers=False when creating the FastAPI app to prevent FastAPI from automatically including a server entry using the root_path in the OpenAPI schema.

Custom servers in OpenAPI with root_path example

When creating a FastAPI app with root_path and custom servers, the generated OpenAPI schema includes the root_path server at the beginning. Example: servers=[{"url": "https://stag.example.com", "description": "Staging environment"}, {"url": "https://prod.example.com", "description": "Production environment"}] with root_path="/api/v1" generates servers starting with {"url": "/api/v1"} followed by the custom servers.

Give your agent this brain