john/prompts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

uvicorn settings

Browse Source
This commit is contained in:
John Lancaster
2026-06-17 00:28:59 -05:00
parent 78fa9235d3
commit 6e32955533
3 changed files with 235 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/fastapi-uv-docker/SKILL.md
+42 -10
View File
@@ -24,6 +24,7 @@ Load these references only when needed:
- FastAPI patterns and app structure: [./references/fastapi-best-practices.md](./references/fastapi-best-practices.md)
- uv project layout and dependency management: [./references/uv-project-layout.md](./references/uv-project-layout.md)
- uvicorn CLI settings reference: [./references/uvicorn-settings.md](./references/uvicorn-settings.md)
- Docker and cloud-native patterns: [./references/docker-cloud-native.md](./references/docker-cloud-native.md)
---
@@ -45,6 +46,7 @@ Before making changes, map the current state across six areas. Produce a short g
Load [./references/fastapi-best-practices.md](./references/fastapi-best-practices.md) for structure rules.
Load [./references/uv-project-layout.md](./references/uv-project-layout.md) for uv migration rules.
Load [./references/uvicorn-settings.md](./references/uvicorn-settings.md) for uvicorn CLI reference.
Completion check: You can name every gap before touching any file.
@@ -209,28 +211,58 @@ Completion check: `uv run uvicorn my_app.main:app --reload` starts with no impor
### Step 4: uvicorn Production Configuration
**Never** configure uvicorn inside application code. Pass all settings via CLI or environment.
Load [./references/uvicorn-settings.md](./references/uvicorn-settings.md) for the full settings reference.
**Never** configure uvicorn inside application code. Pass all settings via CLI or environment variables (`UVICORN_*` prefix).
```bash
# Development
uv run uvicorn my_app.main:app --reload --host 127.0.0.1 --port 8000
# Development — reload only; never in production
uv run uvicorn my_app.main:app \
--reload \
--host 127.0.0.1 \
--port 8000 \
--log-level debug
# Production (single process — let orchestrator handle replication)
# Production — single process (orchestrator handles replication)
uv run uvicorn my_app.main:app \
--host 0.0.0.0 \
--port 8000 \
--workers 1 \
--loop uvloop \
--http h11 \
--loop auto \
--http auto \
--log-level info \
--access-log \
--proxy-headers \
--forwarded-allow-ips '*'
--forwarded-allow-ips '*' \
--timeout-graceful-shutdown 30
```
**When to use `--workers > 1`:** Only for single-server Docker Compose deployments where you cannot replicate at the orchestrator level. For Kubernetes / cloud run: always `--workers 1` and scale via replicas.
**Key flags for production:**
**`--proxy-headers`** is required whenever the container sits behind a reverse proxy (nginx, traefik, cloud load balancer) — it makes FastAPI trust `X-Forwarded-For` and `X-Forwarded-Proto`.
| Flag | Value | Reason |
|------|-------|--------|
| `--host 0.0.0.0` | Required in containers | Bind to all interfaces, not just loopback |
| `--workers 1` | Kubernetes/Cloud Run | Orchestrator replicates containers |
| `--loop auto` | Default | Uses `uvloop` when available (install `uvicorn[standard]`) |
| `--http auto` | Default | Uses `httptools` when available |
| `--proxy-headers` | Behind any proxy | Trusts `X-Forwarded-For`, `X-Forwarded-Proto` |
| `--forwarded-allow-ips '*'` | Container/K8s | Trusts proxy headers from all IPs (safe when inside a trusted network) |
| `--timeout-graceful-shutdown 30` | Prod | Seconds to wait before force-closing requests on shutdown |
| `--no-access-log` | High-traffic prod | Disable per-request logs if using structured app-level logging |
**Environment variable equivalents** (useful in `docker-compose.yml` / K8s manifests):
```bash
UVICORN_HOST=0.0.0.0
UVICORN_PORT=8000
UVICORN_WORKERS=1
UVICORN_LOG_LEVEL=info
UVICORN_PROXY_HEADERS=true
UVICORN_FORWARDED_ALLOW_IPS=*
```
**`--reload` and `--workers` are mutually exclusive** — never combine them.
**When to use `--workers > 1`:** Only for Docker Compose on a single host where orchestrator-level replication is not available. For Kubernetes / Cloud Run / Fargate: always `--workers 1` and scale via replicas — this gives predictable per-container memory and cleaner crash isolation.
Completion check: `curl http://localhost:8000/healthz` returns `{"status":"ok"}`.