Allotjar FastAPI en un VPS amb Uvicorn i Nginx

Una API que respon a localhost encara no està publicada per als usuaris. FastAPI fa servir ASGI i necessita un servidor compatible com Uvicorn, un gestor de processos que el mantingui actiu i una ruta pública HTTPS. Un VPS et permet instal·lar i controlar aquestes peces; les actualitzacions, les claus, el tallafoc, les dades i la recuperació queden a càrrec teu.

Aquesta guia fa servir Debian o Ubuntu, Uvicorn, systemd i Nginx. app.main i l’objecte app són exemples: adapta la importació al teu repositori. Si el projecte també té un frontend, una base de dades, una cua o tasques programades, planifica i prova cada servei per separat.

1. Troba l’objecte ASGI que has d’executar

Busca requirements.txt o pyproject.toml, la versió de Python necessària i on es crea FastAPI(). Pot ser que l’aplicació s’exposi com main:app, app.main:app o una altra ruta. Si fa servir una fàbrica que retorna l’app, Uvicorn també admet --factory; comprova el nom i la signatura abans d’utilitzar-la.

Executa l’API localment i prova rutes reals, autenticació, pujades, errors i dependències externes. Revisa el codi generat per IA per detectar credencials a Git, claus que podrien acabar al JavaScript del navegador, CORS massa ampli i ajustos que només funcionin a localhost. Decideix si /docs, /redoc i /openapi.json han de ser públics en el teu cas.

2. Prepara Python en un VPS

Tria un VPS Hostbrid amb Debian o Ubuntu compatible amb la teva versió de Python. Connecta-t’hi per SSH, aplica actualitzacions i obre només els ports necessaris. Crea un compte de servei sense privilegis d’administrador i un entorn virtual:

sudo apt update
sudo apt install git python3-venv nginx
sudo adduser --system --group --home /srv/fastapi fastapi
sudo -u fastapi python3 -m venv /srv/fastapi/venv

Clona el projecte a /srv/fastapi/current i protegeix les credencials d’accés al repositori privat. Instal·la les dependències declarades per l’app dins de l’entorn virtual:

sudo -u fastapi /srv/fastapi/venv/bin/pip install -r /srv/fastapi/current/requirements.txt

Comprova que Uvicorn és una dependència de producció; alguns projectes ja el declaren i d’altres l’han d’afegir. No instal·lis l’aplicació al Python global del sistema.

3. Separa secrets i configuració

Desa les variables de producció fora de Git en un fitxer restringit, per exemple /etc/fastapi.env. El codi les ha de llegir explícitament. Fes servir valors nous per a la base de dades, l’autenticació, el correu i les API externes. No publiquis un .env, una clau privada o un token al frontend, al repositori ni als logs.

Si un navegador crida l’API des d’un altre domini, configura CORS amb els orígens exactes que necessita el web. No facis servir un comodí sense entendre’n l’efecte: quan hi ha credencials, FastAPI exigeix orígens, mètodes i capçaleres explícits. CORS és una política del navegador, no substitueix l’autenticació ni limita els clients de servidor a servidor.

Si l’API desa dades persistents, identifica’n la ubicació i els permisos d’escriptura. Fes-ne una còpia abans de migrar l’esquema i documenta com restaurar-la. Desa les pujades dels usuaris separades del codi i decideix quines mètriques, logs i dades personals cal conservar.

4. Mantén Uvicorn en execució

Prova primer la ruta d’importació real. Aquest exemple carrega app des de app/main.py i escolta només a loopback perquè el trànsit públic hagi de passar per Nginx:

cd /srv/fastapi/current
sudo -u fastapi /srv/fastapi/venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8000

Per a una fàbrica compatible, adapta la ruta i afegeix --factory. Comença amb un procés i mesura’n l’ús. Afegir workers pot aprofitar més nuclis, però cada procés acostuma a necessitar la seva pròpia memòria; no copiïs un nombre universal sense mesurar l’API i la talla del VPS.

Quan funcioni la prova, crea /etc/systemd/system/fastapi.service perquè Uvicorn arrenqui amb el sistema i es recuperi després d’una fallada:

[Unit]
Description=FastAPI application
After=network.target

[Service]
User=fastapi
Group=fastapi
WorkingDirectory=/srv/fastapi/current
EnvironmentFile=/etc/fastapi.env
ExecStart=/srv/fastapi/venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8000 --proxy-headers --forwarded-allow-ips=127.0.0.1
Restart=on-failure

[Install]
WantedBy=multi-user.target

Adapta la importació, revisa els permisos del fitxer d’entorn i executa sudo systemctl daemon-reload i sudo systemctl enable --now fastapi. Consulta sudo systemctl status fastapi, journalctl -u fastapi i fes una petició local a http://127.0.0.1:8000/. Uvicorn només ha de confiar en les capçaleres reenviades pel proxy que controles.

5. Posa Nginx i HTTPS al davant

Configura Nginx per rebre peticions i reenviar-les al procés local. Canvia el domini i conserva la ruta / que espera l’API:

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        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;
    }
}

Activa el lloc i valida’l amb sudo nginx -t abans de recarregar. Apunta el DNS al VPS, permet el trànsit web necessari i configura un certificat TLS. Redirigeix HTTP a HTTPS. Si fas servir WebSockets o pujades grans, configura i prova aquests límits expressament.

FastAPI genera documentació OpenAPI i la pot servir a /docs i /redoc. Revisa’n el contingut i la política d’accés; pots desactivar aquestes rutes a la configuració de l’app si no han de ser públiques. Amagar la documentació no protegeix una API: cada endpoint encara necessita controls d’accés.

6. Prova l’API i la recuperació

Des d’una altra màquina, prova el domini, HTTPS, autenticació, CORS des del frontend, errors, límits de pujada i dependències. Reinicia systemd i comprova que l’API torna. Revisa els logs sense mostrar secrets ni cossos amb dades sensibles. Automatitza les còpies de la base de dades i dels fitxers i prova una restauració. Si executes migracions o tasques d’arrencada, controla’n l’ordre perquè diverses instàncies no les repeteixin alhora.

Aquest desplegament és autogestionat: Hostbrid proporciona el VPS amb accés root, però tu instal·les i mantens Python, FastAPI, Uvicorn, Nginx, HTTPS, actualitzacions, tallafoc i còpies. Compara les talles VPS i els preus vigents amb l’ús mesurat de l’API, els workers i els serveis associats.

Fonts oficials: FastAPI sobre el desplegament, els conceptes, els workers, CORS, Uvicorn darrere d’un proxy i el proxy invers Nginx.