Desplegar FastAPI en un VPS con Uvicorn y Nginx

Una API que responde en localhost todavía no está publicada para tus usuarios. FastAPI usa ASGI y necesita un servidor compatible, como Uvicorn, además de un proceso que lo mantenga activo y una ruta HTTPS pública. Un VPS te permite instalar y controlar estas piezas; la operación diaria —actualizaciones, claves, firewall, datos y recuperación— queda a tu cargo.

Esta guía usa Debian o Ubuntu, Uvicorn, systemd y Nginx. Los módulos app.main y el objeto app son ejemplos: adapta el import a tu repositorio. Si tu proyecto incluye también una web frontend, una base de datos, colas o tareas programadas, planifica y prueba cada servicio por separado.

1. Encuentra el objeto ASGI correcto

Busca requirements.txt o pyproject.toml, la versión de Python requerida y dónde se crea FastAPI(). Un proyecto puede exponerlo como main:app, app.main:app u otra ruta de importación. Si usa una fábrica que devuelve la aplicación, Uvicorn también admite --factory; comprueba el nombre y la firma antes de copiar un comando.

Ejecuta la API en local y prueba rutas reales, autenticación, cargas, respuestas de error y dependencias externas. Revisa el código generado por IA para identificar credenciales en Git, claves que terminarían en JavaScript del navegador, CORS demasiado amplio y configuración que solo funciona en localhost. Decide si las páginas /docs, /redoc y /openapi.json deben estar disponibles públicamente en tu caso.

2. Prepara Python en un VPS

Elige un VPS Hostbrid con Debian o Ubuntu compatible con tu versión de Python. Conéctate por SSH, aplica actualizaciones y abre solo los puertos que usarás. Crea una cuenta de servicio sin privilegios de administrador y un entorno 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 proyecto en /srv/fastapi/current y protege cualquier credencial de acceso al repositorio privado. Instala las dependencias declaradas por la app dentro del entorno virtual:

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

Comprueba que Uvicorn está instalado como dependencia de producción; algunas apps ya lo declaran y otras necesitan añadirlo. No instales la aplicación en el Python global del sistema.

3. Separa secretos y configuración

Guarda variables de producción fuera de Git en un archivo restringido, por ejemplo /etc/fastapi.env. Tu aplicación debe leerlas explícitamente. Usa claves nuevas y valores de producción para base de datos, autenticación, servicios de correo y API externas. Nunca publiques un .env, una clave privada o un token en el frontend, en el repositorio o en los logs.

Si el navegador llama a la API desde otro dominio, configura CORS con los orígenes exactos que necesita esa web. No uses un comodín sin entender sus efectos: con credenciales, FastAPI requiere orígenes, métodos y cabeceras explícitos. CORS es una política del navegador, no sustituye la autenticación ni limita clientes que llamen a la API desde un servidor.

Si la API procesa datos persistentes, identifica dónde viven y quién escribe en ellos. Antes de migrar el esquema, toma una copia y define cómo restaurarla. Guarda los archivos de usuario separados del código y decide qué métricas, logs y datos personales realmente necesitas conservar.

4. Ejecuta Uvicorn de forma persistente

Prueba primero el punto de entrada concreto. Este ejemplo carga app desde app/main.py y escucha solo en loopback, de modo que el tráfico público entre por Nginx:

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

Para una fábrica compatible, adapta la ruta y añade --factory. Mantén inicialmente un proceso y mide el consumo. Añadir workers puede usar más núcleos, pero cada proceso suele necesitar su propia memoria; no copies un número universal sin medir tu API y el tamaño del VPS.

Cuando la prueba funcione, crea /etc/systemd/system/fastapi.service para iniciar Uvicorn al arrancar y recuperarlo tras un fallo:

[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 el import, revisa permisos del archivo de entorno y ejecuta sudo systemctl daemon-reload, sudo systemctl enable --now fastapi. Comprueba sudo systemctl status fastapi, journalctl -u fastapi y una petición local a http://127.0.0.1:8000/. Uvicorn solo debe confiar cabeceras reenviadas desde el proxy que controlas.

5. Publica la API detrás de Nginx y HTTPS

Configura Nginx para recibir las peticiones y reenviarlas al proceso local. Cambia el nombre de dominio y conserva la ruta / que espera la 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 sitio y valida la configuración con sudo nginx -t antes de recargar el servicio. Apunta el DNS al VPS, permite el tráfico web necesario y configura un certificado TLS. Redirige HTTP a HTTPS; si tienes WebSockets o cargas grandes, configura y prueba esos límites expresamente.

FastAPI genera documentación OpenAPI y puede servirla en /docs y /redoc. Revisa el contenido de la especificación y la política de acceso; puedes desactivar esas rutas en la configuración de la aplicación si no deben ser públicas. No asumas que ocultar la documentación protege una API: cada endpoint aún necesita controles de acceso.

6. Comprueba la API y la recuperación

Desde otra máquina prueba el dominio, HTTPS, autenticación, CORS desde el frontend, rutas de error, límites de carga y dependencias. Reinicia systemd y confirma que la API regresa. Revisa los logs sin volcar secretos ni cuerpos con datos sensibles. Automatiza copias de la base de datos y archivos y prueba una restauración. Si ejecutas migraciones o tareas de arranque, controla el orden para evitar que varias instancias las repitan a la vez.

Este despliegue es autogestionado: Hostbrid suministra el VPS con acceso root, pero tú instalas y mantienes Python, FastAPI, Uvicorn, Nginx, HTTPS, actualizaciones, firewall y copias. Compara las tallas VPS y los precios vigentes con el consumo medido de la API, sus workers y servicios asociados.

Fuentes oficiales: FastAPI sobre despliegue, conceptos, workers, CORS, Uvicorn detrás de proxy y proxy inverso Nginx.