Come si distribuisce un'app FastAPI in produzione?

Question

Accepted Answer

FastAPI è un'applicazione **ASGI**, quindi il deployment in produzione utilizza un server ASGI — tipicamente **Uvicorn** (spesso gestito da **Gunicorn** per più worker), dietro un reverse proxy come nginx. La containerizzazione (Docker) è l'approccio moderno più comune.

## Lo stack del server di produzione

```bash
# ❌ the dev server (with --reload) is NOT for production
uvicorn main:app --reload

# ✅ production: Gunicorn managing multiple Uvicorn workers (uses all CPU cores)
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
# -w 4 → 4 worker processes (rule of thumb: ~2 × CPU cores)
```

```text
Client → NGINX (reverse proxy: TLS, static files, load balancing)
           → GUNICORN (process manager) → UVICORN workers (run the ASGI app)
Multiple workers let FastAPI use multiple CPU cores (each worker = one process).
```

## Containerizzare l'app (comune)

```dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["gunicorn", "main:app", "-w", "4", "-k", "uvicorn.workers.UvicornWorker", "--bind", "0.0.0.0:8000"]
```

Un container incapsula l'app e le sue dipendenze per un deployment coerente negli ambienti (quindi esegui su Kubernetes, ECS, o un PaaS come Railway/Render/Fly).

## La checklist di produzione

```text
1. Config & secrets via environment variables (not in code); validate at startup
2. Multiple workers (Gunicorn + Uvicorn workers) for CPU utilization
3. HTTPS/TLS (at nginx or the platform/load balancer)
4. A real database (PostgreSQL) + connection pooling; run migrations (Alembic)
5. CORS configured to an allowlist (not "*") for browser clients
6. Logging + error monitoring (Sentry) + health-check endpoint
7. A separate worker service (Celery/ARQ) + broker (Redis) for background jobs
8. Horizontal scaling: multiple instances behind a load balancer — keep app STATELESS
   (sessions/state in Redis, not process memory)
```

## Async e statelessness

```text
✓ Each worker runs its own event loop → workers give parallelism, async gives concurrency
✓ Keep the app STATELESS so you can run many instances behind a load balancer
```

## Perché è importante

Distribuire FastAPI correttamente è essenziale per portare le applicazioni in produzione, e comporta considerazioni importanti specifiche della sua natura **ASGI** che differiscono dalla configurazione di sviluppo.

Comprendere lo stack del server di produzione è fondamentale: il server di sviluppo (`uvicorn --reload`) non è per la produzione, quindi esegui l'app tramite un server ASGI — **worker Uvicorn gestiti da Gunicorn** per più processi (sfruttando tutti i core della CPU, poiché ogni worker esegue il proprio event loop), tipicamente dietro nginx per TLS e load balancing. **La containerizzazione (Docker)** è l'approccio moderno comune per deployment coerenti e portatili.

Oltre la configurazione del server, la checklist di produzione copre questioni critiche per sicurezza e affidabilità: configurazione e secrets tramite variabili d'ambiente (mai nel codice), HTTPS, un vero database con migrazioni e pooling, CORS appropriato, logging e monitoring, servizi worker separati per job in background, e — per il scaling — l'esecuzione di **più istanze stateless** dietro un load balancer (mantenendo lo stato in Redis, non nella memoria del processo).

Sapere come distribuire FastAPI con il giusto stack di server ASGI, containerizzazione, più worker, e hardening di produzione è una conoscenza importante di livello senior, poiché ogni vera applicazione FastAPI deve essere distribuita correttamente per essere performante, sicura e scalabile — rendendo questo un argomento frequentemente rilevante e professionalmente essenziale per il rilascio di API di produzione.