Déployer FastAPI sur un VPS : guide complet production

FastAPI tire toute sa performance du modèle ASGI asynchrone : connexions WebSocket persistantes, streaming de réponses et appels concurrents vers d'autres services. Les plateformes serverless coupent souvent les connexions longues et facturent chaque requête, ce qui pénalise une API à fort débit ou temps réel. Sur un VPS, vous lancez Uvicorn piloté par Gunicorn avec autant de workers que de cœurs, vous gardez les connexions ouvertes aussi longtemps que nécessaire et vous placez Nginx en frontal pour le TLS et le buffering. Vous contrôlez aussi le pool de connexions vers PostgreSQL et le cache Redis, deux leviers essentiels quand la charge monte — le débit réellement tenu se mesure sur votre propre trafic.

Une API FastAPI est légère : 1 vCPU et 1 Go de RAM suffisent pour démarrer, mais visez 2 vCPU et 2 Go dès que vous ajoutez une base de données et un cache sur le même VPS. Pour une charge soutenue (>100 req/s), comptez 4 vCPU et 4 Go minimum.

Versions recommandées en 2025 : Python 3.11+ (3.12 pour les performances maximales), FastAPI 0.115+ (support complet de Pydantic v2 et des annotations Python 3.10+), Uvicorn 0.30+ (correctifs de stabilité event loop). Installez via Docker avec l'image python:3.12-slim pour un démarrage rapide, ou depuis le dépôt officiel avec pip install fastapi[standard]>=0.115 uvicorn[standard]>=0.30 gunicorn>=22.0.

Du côté infrastructure : Docker Engine 24+, Docker Compose v2 (plugin intégré, docker compose), Nginx 1.24+ en reverse proxy, et un domaine pointé vers le VPS pour le certificat TLS. Ubuntu 22.04/24.04 LTS est la base recommandée ; Debian 12 fonctionne également.

Pour les applications FastAPI en production, asyncpg combiné à SQLAlchemy 2.x (mode async) offre un excellent équilibre entre performances et maintenabilité. Configurez le pool de connexions en fonction de la charge attendue :

from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker

engine = create_async_engine(
    DATABASE_URL,
    pool_size=10,        # connexions persistantes
    max_overflow=20,     # connexions supplémentaires sous pic
    pool_timeout=30,     # secondes avant erreur
    pool_recycle=1800,   # recycle après 30 min pour éviter les timeouts PostgreSQL
    echo=False,
)

AsyncSessionLocal = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)

Injectez la session dans vos routes via une dépendance FastAPI :

async def get_db():
    async with AsyncSessionLocal() as session:
        yield session

Pour les migrations de schéma, Alembic est l'outil standard. Initialisez-le dans votre projet (alembic init migrations) puis configurez alembic.ini pour pointer sur votre DATABASE_URL. Les commandes essentielles :

# Générer une migration depuis vos modèles SQLAlchemy
alembic revision --autogenerate -m "add_users_table"

# Appliquer les migrations en attente
alembic upgrade head

# Vérifier l'état courant
alembic current

En production, exécutez alembic upgrade head avant de démarrer l'API — ajoutez-le comme commande d'init dans votre docker-compose.yml ou dans un script de démarrage séparé. Ne lancez jamais les migrations depuis plusieurs instances simultanément.

Un pipeline GitHub Actions simple suffit pour la majorité des projets FastAPI : build de l'image, push vers un registry, et déploiement sur le VPS par SSH avec zero-downtime.

# .github/workflows/deploy.yml
name: Deploy FastAPI
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build & push Docker image
        run: |
          docker build -t ghcr.io/${{ github.repository }}:${{ github.sha }} .
          echo ${{ secrets.GITHUB_TOKEN }} | docker login ghcr.io -u ${{ github.actor }} --password-stdin
          docker push ghcr.io/${{ github.repository }}:${{ github.sha }}

      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.VPS_HOST }}
          username: deploy
          key: ${{ secrets.VPS_SSH_KEY }}
          script: |
            cd /opt/myapp
            export IMAGE_TAG=${{ github.sha }}
            docker compose pull api
            docker compose up -d --no-deps api
            docker compose exec api alembic upgrade head

L'option --no-deps sur docker compose up redémarre uniquement le conteneur api sans toucher db ni redis, ce qui garantit un zero-downtime pour les services tiers. Docker Compose démarre le nouveau conteneur avant d'arrêter l'ancien (rolling update interne).

Pour des déploiements plus robustes avec rollback instantané, envisagez de tagger vos images avec le SHA du commit et de conserver les 3 dernières versions localement — docker image prune avec --filter until=72h nettoie les anciennes images automatiquement.

Accédez aux logs Uvicorn directement via Docker :

# Logs en temps réel
docker compose logs -f api

# 100 dernières lignes
docker compose logs --tail=100 api

Pour des logs structurés en JSON (indexables par un agrégateur comme Loki ou Elasticsearch), remplacez le logger Python standard par loguru ou structlog :

from loguru import logger
import sys

logger.remove()
logger.add(sys.stdout, format="{time} {level} {message}", serialize=True)

@app.middleware("http")
async def log_requests(request, call_next):
    logger.info("request", method=request.method, url=str(request.url))
    response = await call_next(request)
    logger.info("response", status=response.status_code)
    return response

Pour exposer des métriques Prometheus, ajoutez un endpoint /metrics basique avec prometheus-fastapi-instrumentator :

from prometheus_fastapi_instrumentator import Instrumentator

Instrumentator().instrument(app).expose(app, endpoint="/metrics")

Restrictez ensuite /metrics à votre réseau interne depuis Nginx (directive allow 127.0.0.1; deny all;) pour éviter d'exposer les métriques publiquement.

Worker timed out (pid XXXXX) — Gunicorn tue un worker qui n'a pas répondu dans le délai --timeout. Causes fréquentes : une route synchrone (def au lieu de async def) bloque l'event loop, ou une opération bloquante (lecture fichier, appel réseau) s'exécute sans asyncio.run_in_executor. Augmenter --timeout masque le problème ; la bonne correction est de rendre la route asynchrone ou de déléguer le travail bloquant.

Address already in use (port 8000) — Un processus Gunicorn précédent est encore actif. En Docker : docker compose down puis docker compose up -d force la recréation du conteneur et libère le port. Vérifiez avec docker ps -a qu'aucun conteneur zombie ne tourne.

502 Bad Gateway après un déploiement — Nginx a transmis la requête à l'API pendant son redémarrage. Attendez 10-15 secondes que le healthcheck Docker confirme que le nouveau conteneur est healthy avant de considérer le déploiement terminé. Ajoutez proxy_read_timeout 60; dans Nginx pour absorber les démarrages lents.

CORS en production : No 'Access-Control-Allow-Origin' header — FastAPI sert les origines déclarées dans CORSMiddleware. Vérifiez que CORS_ORIGINS dans votre .env contient exactement l'URL du frontend (protocole + domaine + port si non standard, sans slash final). Une valeur ["*"] fonctionne en développement mais ne doit jamais partir en production.

Connexion DB refusée au démarrage — L'API démarre avant que PostgreSQL soit prêt. Le depends_on avec condition: service_healthy dans Docker Compose résout ce cas. En Kubernetes ou sur des déploiements sans Compose, implémentez une boucle de retry avec backoff exponentiel dans le code de démarrage de l'application.

Le Marketplace ServOrbit propose un template FastAPI Stack préconfiguré : Python 3.12, Uvicorn, Gunicorn, Nginx et PostgreSQL 16 sont installés automatiquement sur votre VPS dès la commande. Pas de session SSH pour l'installation de base — vous arrivez directement à l'étape de cloner votre dépôt et de lancer Uvicorn. La fiche marketplace contient les spécifications exactes, les cas d'usage et un guide de première connexion.