La respuesta corta
Para desplegar FastAPI en producción, fastapi dev y uvicorn --reload no son el servidor. Esos comandos son de desarrollo. El deploy corre Uvicorn en un contenedor, en 0.0.0.0 y en el puerto del comando de arranque, con las dependencias fijadas en la imagen, la configuración en variables de entorno y un solo proceso de servidor en ese contenedor.
Si estás eligiendo hosting para FastAPI, en Unbroker ese camino es un servicio con Dockerfile y pide Pro. Los builds de Dockerfile no están en Free. La página de producto es Desplegar FastAPI. Los pasos están en Deploy a FastAPI application.
Servidor de desarrollo y servidor de producción
fastapi dev arranca el modo de desarrollo. El reload está prendido y el servidor escucha en 127.0.0.1, la dirección que la máquina usa para hablar consigo misma. La CLI de FastAPI dice que para producción uses fastapi run. fastapi run apaga el reload y escucha en 0.0.0.0, así el proceso se alcanza desde afuera de la máquina. En un contenedor, esa es la dirección que necesitás.
La página de deploy de Uvicorn dice que uvicorn --reload es para desarrollo local. La página de settings dice que --host arranca en 127.0.0.1, y que --host 0.0.0.0 es cómo la aplicación queda disponible en la red. --reload y --workers no van juntos.
Desarrollo (fastapi dev, uvicorn --reload) | Servidor de producción | |
|---|---|---|
| Proceso | Modo de desarrollo. Recarga cuando cambia el código. No es el comando del release. | Uvicorn sin reload, en un contenedor. fastapi run es el comando de producción de la CLI y también apaga el reload. |
| Dirección | 127.0.0.1. Otras máquinas no llegan. fastapi dev usa el puerto 8000. | 0.0.0.0 y el puerto del comando. El ejemplo de Unbroker es ${PORT:-8000}. |
| Dependencias | Lo que tenga instalado el entorno local. | Un requirements.txt commiteado con versiones resueltas, instalado en la imagen. |
| Configuración | Muchas veces un .env local. | Variables de entorno de runtime. No van en el repo ni se copian a la imagen. |
| Trabajo largo | Es fácil dejarlo en el proceso del request. | Un worker con una cola durable, cuando el trabajo tiene que sobrevivir un reinicio. |
Un Dockerfile de producción
El Dockerfile de la guía de Unbroker es el archivo que se publica. La página de contenedores de FastAPI usa su propia imagen base de Python y fastapi run en un puerto fijo. La guía usa python:3.12-slim, instala los requirements commiteados, baja a un usuario que no es root y arranca Uvicorn para que el shell expanda PORT.
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
COPY main.py ./
RUN useradd --uid 10001 --create-home appuser
USER appuser
ENV PORT=8000
CMD ["sh", "-c", "exec uvicorn main:app --host 0.0.0.0 --port ${PORT:-8000}"]
Anotá las versiones resueltas en requirements.txt y commiteá ese archivo, para que la imagen instale un conjunto conocido. La guía pide mantener la imagen base y esas dependencias al día con tu revisión habitual. Copiá el archivo de requirements antes que el de la aplicación. La página de contenedores de FastAPI pone primero el archivo de dependencias por la misma razón: la capa de instalación se puede reutilizar cuando solo cambia el código.
La línea CMD está en la forma exec de Docker, el array JSON. La página de contenedores de FastAPI dice que uses esa forma para que el proceso pueda apagarse con gracia y corran los eventos de lifespan. La forma shell, un CMD uvicorn ... pelado, no lo hace. Este comando igual arranca un shell, porque el shell es el que expande PORT. exec reemplaza ese shell por Uvicorn. La guía dice las dos partes: el shell expande PORT, y exec deja que la aplicación reciba las señales de apagado. Sin exec, la señal se queda en sh y el servidor no es el proceso que la recibe.
${PORT:-8000} escucha en PORT cuando está definida, y en 8000 solo cuando PORT está vacía. ENV PORT=8000 es el default adentro de la imagen. Escuchá en 0.0.0.0, no en 127.0.0.1. El proceso corre como appuser, no como root.
Un deploy de FastAPI con Docker arranca de este archivo en la raíz del repositorio. El chequeo local de la guía construye la imagen y pide /health antes de conectar el repositorio. La misma forma está en Deploy a Docker container. Un archivo compose que levanta la API, una base y un worker como un solo stack es otro esquema: Docker Compose en producción.
La página de contenedores de FastAPI también dice que la imagen vieja tiangolo/uvicorn-gunicorn-fastapi está deprecada. Construí desde una imagen base de Python, no desde esa imagen.
Workers, procesos y réplicas
El ejemplo de la guía tiene un proceso de servidor por contenedor. Es el caso que FastAPI documenta cuando la replicación vive afuera del contenedor.
La página de contenedores dice que, si un clúster o una plataforma replica contenedores, conviene un solo proceso de Uvicorn en cada uno, no --workers. --workers arranca varios procesos worker adentro de un contenedor, con un manager delante. FastAPI dice que ese manager de más es complejidad que ya cubriste si la plataforma crea las copias. Uvicorn documenta --workers en su página de deploy. El número default es 1, o $WEB_CONCURRENCY si esa variable está definida. No definas WEB_CONCURRENCY salvo que quieras que el default la siga. El comando de la guía no pasa --workers.
Hay otro caso. FastAPI dice que --workers puede tener sentido en una app simple de un solo servidor, o con Docker Compose en una máquina, cuando no tenés otra forma de correr varios contenedores y repartir los requests. Ese no es el ejemplo de Unbroker. Los workers de Uvicorn en producción son esa elección: varios procesos en un contenedor, o un proceso y más contenedores. Esta nota no elige un número de workers.
En Unbroker, Free corre una réplica. Pro puede configurar réplicas, hasta el límite de la celda compartida de la tabla de planes. El autoscaling de réplicas no está en Free. Cómo se suman y se sacan las copias está en Autoscaling de réplicas. Un servicio worker es otra cosa: la guía de workers dice que corren una réplica.
Settings y secretos
La página de settings de FastAPI dice que las claves secretas, las credenciales de la base y el resto de la configuración suelen venir de variables de entorno, porque cambian y porque muchas son sensibles. Una variable de entorno es un string afuera del código Python. Lo que no es un string, incluido un número, lo tiene que parsear la aplicación.
pydantic-settings es opcional. BaseSettings lee esas variables, sin importar mayúsculas, y las valida en los tipos que declarás. Un .env es la forma local de la misma idea. En producción, definí los mismos nombres como variables de runtime. No commitees el archivo y no lo copies a la imagen.
Un secreto copiado a una capa de la imagen se queda en el artefacto aunque una capa posterior borre el archivo. La guía de Docker dice que sumes .env, credenciales locales y otros archivos locales al .dockerignore cuando el COPY es amplio, y que los secretos de la aplicación vayan por variables de runtime. Esa guía es Deploy a Docker container.
En Unbroker, abrí las variables del servicio y definí el valor para el entorno que tiene que recibirlo: Production, Preview o All. Una credencial de base de producción no va en All, salvo que los entornos de preview tengan que recibirla. Usá una variable de servicio para la configuración de una sola aplicación. Las variables compartidas del proyecto son para un valor que usan varios servicios, y requieren Pro. Una variable de servicio pisa una compartida con la misma clave. Desplegá de nuevo para que la revisión en marcha use el valor nuevo. No imprimas todo el entorno mientras depurás. El alcance está en Variables de entorno y secretos, y los pasos en Configure environment variables and secrets.
Base de datos, pools y migraciones
El ejemplo de la guía de FastAPI no tiene base. Cuando agregás una, dice que uses una variable de conexión de runtime, un pool de conexiones y un paso deliberado de migración de schema. No corras migraciones durante el build de la imagen.
En Unbroker hay dos caminos de PostgreSQL. Un nodo de Apps es un servicio de base privado dentro del proyecto. Un clúster gestionado es un host de base que opera el proveedor. El schema y las migraciones siguen siendo tuyos. La guía de conexión arranca de Unbroker Pro y de un recurso PostgreSQL que ya existe. Las bases gestionadas no están en Free. Guardá las credenciales en las variables de runtime del servicio. Un comando que muestra un connection string puede imprimir un secreto, así que ese output no va al repo, al chat ni a los logs. No apagues la verificación del certificado para pasar un error de conexión, y no expongas la base a internet para diagnosticar una conexión privada. Los pasos están en Connect your application to PostgreSQL. Operar la base está en Postgres en producción.
Acotá el pool y definí timeouts. La fila de “demasiadas conexiones” de la guía es el tamaño del pool multiplicado por procesos y por réplicas. Un proceso por contenedor no mantiene chico el total si cada réplica abre un pool grande.
Corré la migración una vez, con las credenciales de runtime, antes de que la versión nueva reciba tráfico. Los conceptos de deploy de FastAPI dicen que un paso previo, como una migración, tiene que correr una sola vez. Si la corre cada proceso, esos procesos trabajan en paralelo y la migración puede entrar en conflicto consigo misma. Si el proyecto ya usa Alembic, ese comando es este paso. Esta nota no le agrega flags. En Unbroker, los comandos de migración requieren Pro. Qué deja atrás un rollback de código está en Migraciones de base de datos en el deploy.
Trabajo en segundo plano
BackgroundTasks corre después de la respuesta, en el mismo proceso. La página de background tasks de FastAPI las usa cuando el cliente no tiene que esperar, por ejemplo un aviso por email o un archivo que el request ya aceptó. La función puede ser async def o un def común.
La misma página tiene una salvedad. Si el trabajo es pesado y no necesita la memoria de ese proceso, usá una herramienta de cola. La página nombra Celery como ejemplo. Esas herramientas necesitan una cola de mensajes y pueden correr en otros procesos y en otras máquinas. La guía de workers de Unbroker no nombra una librería. Dice que el worker y la cola durable son piezas distintas, y que un loop sobre un array en memoria no es entrega durable.
Si el trabajo tiene que sobrevivir un reinicio, BackgroundTasks no es el lugar. Viven en el proceso del servidor. Cuando ese proceso se detiene, la tarea se detiene con él. Poné el consumidor en su propio servicio worker. El comando de arranque tiene que lanzar el consumidor y quedarse vivo mientras espera. Un script que procesa un ítem y sale es un job programado o un comando de una vez, no un worker. Los workers requieren Pro y corren una réplica. No tienen URL pública. El corte está en Workers en segundo plano y cron, y los pasos en Deploy a background worker.
Health checks y fallos de arranque
El health check de FastAPI en la guía es GET /health. El ejemplo devuelve {"ok": True}. Después del deploy, abrí /health en la URL del servicio. El ejemplo también tiene /api/message.
Dos fallos aparecen antes de que haga falta una máquina más grande. Un error de import suele querer decir que la ruta main:app no coincide con el repositorio, o que una dependencia no entró en la imagen. Un contenedor que responde en local y no se alcanza después del deploy suele necesitar el host o el puerto: 0.0.0.0, y el puerto en el que el comando escuchó de verdad. Leé los logs de runtime antes de subir recursos. Por dónde empezar cuando un release falla está en Depurar un deploy fallido. La guía enlaza el mismo diagnóstico en Diagnose a failed deployment.
Cómo funciona en Unbroker
En Cloud, agregá un servicio de repositorio, elegí el método de build Dockerfile y usá el Dockerfile de la raíz. Configurá las variables de runtime antes de desplegar. Abrí /health en la URL del servicio.
Una API Express en el preset de Node.js es otro camino. El camino público de Node.js gestionado puede calificar para Free, y los builds de Dockerfile no están en Free. Qué cambia después de nodemon está en Express en producción.
La guía arranca de un repositorio Python, un chequeo local con Docker y Unbroker Pro. Los builds de Dockerfile son una capacidad del plan pago. No están en Free. La tabla de planes lista los builds de Dockerfile, los workers, los comandos de migración y las bases gestionadas como no disponibles en Free y disponibles en Pro. La página de precios también lista los Dockerfiles con Pro. Esta nota no describe un camino Free para FastAPI. Lo que puede correr el plan de $0, con Node.js gestionado y sitios estáticos, está en hosting backend gratis sin Dockerfile.
Pro sale $25 por mes con $25 de crédito de uso. El crédito se reinicia en cada ciclo y no se acumula. Si el uso elegible queda por debajo del crédito, el cargo mensual sigue siendo el precio del plan. Si el uso elegible lo pasa, solo se suma la diferencia. Las filas están en precios y en Plans. Presupuestá por separado la API en marcha, el build y cualquier base. La guía dice lo mismo.
¿Cómo despliego una app FastAPI con Docker Compose?
Un archivo de Docker Compose es un inventario de procesos, no algo que Unbroker corre como un proyecto de Compose. Para desplegar una app FastAPI que hoy arrancás con Compose, tratá cada servicio del archivo como un servicio propio de Unbroker.
Cuando creás un proyecto podés pegar un archivo Compose. Unbroker crea un servicio por entrada. Ese camino admite imágenes, builds de repositorio, entorno, depends_on, puertos, comandos y un volumen persistente por servicio. No decide qué es público, dónde viven los datos ni si una base tiene que ser un clúster gestionado. También podés agregar esos servicios a mano.
El servicio de FastAPI sigue siendo el Dockerfile de esta nota: Uvicorn, sin reload, escuchando en 0.0.0.0 y en PORT. Los builds de Dockerfile requieren Pro. Un servicio de Postgres o Redis en el mismo archivo Compose pasa a ser un nodo de base de Apps o una base gestionada, no un proceso metido en la imagen de la API. El mapa campo por campo está en Docker Compose en producción. Los pasos del contenedor están en Deploy a FastAPI application.
Checklist
- Dejá
fastapi devyuvicorn --reloadfuera del comando de producción. - Escuchá en
0.0.0.0. Usá la forma${PORT:-8000}de la guía, y ponéexecdelante de Uvicorn para que las señales de apagado lleguen al servidor. - Instalá un
requirements.txtcommiteado con versiones resueltas. Corré con el usuario no root del Dockerfile de la guía. - Dejá un proceso de servidor en el contenedor. No pases
--workerscuando las réplicas viven afuera, y no definasWEB_CONCURRENCYsi no es a propósito. - Leé la configuración desde variables de entorno. Dejá los secretos fuera del repo y fuera de la imagen.
- Apuntá Postgres a una variable de runtime. Acotá el pool. Acordate del tamaño del pool por procesos por réplicas.
- Corré las migraciones una vez, como paso propio, no durante el build de la imagen y no en cada proceso.
- Poné el trabajo que tiene que sobrevivir un reinicio en un worker con una cola durable. Dejá
BackgroundTaskspara un trabajo corto del proceso web. - Abrí
/healthdespués del deploy. Leé los logs de runtime antes de subir recursos. - Desplegá el servicio Dockerfile en Pro. Los builds de Dockerfile no están en Free.
Preguntas frecuentes
¿Puedo usar uvicorn --reload o fastapi dev en producción?
No. La página de deploy de Uvicorn dice que uvicorn --reload es para desarrollo local. fastapi dev es el modo de desarrollo: el reload está prendido y escucha en 127.0.0.1. La CLI de FastAPI dice que para producción uses fastapi run. El reload mira el árbol de trabajo y no es el proceso de un release. La guía de Unbroker arranca Uvicorn sin reload, en 0.0.0.0, y toma el puerto de PORT.
¿Conviene Uvicorn con --workers o un proceso por contenedor?
Un proceso por contenedor, cuando las copias las crea algo de afuera. La página de contenedores de FastAPI lo dice, y también dice que en ese caso no pases --workers. --workers levanta varios procesos adentro de un solo contenedor. No se puede usar junto con --reload. El default de Uvicorn es 1, o el valor de WEB_CONCURRENCY si esa variable está definida. El ejemplo de Unbroker no pasa --workers. Tiene un proceso de servidor. Cómo se suman copias en Unbroker está en Autoscaling de réplicas.
¿Por qué el contenedor responde en local y después del deploy no se alcanza?
Revisá el host y el puerto. La guía de FastAPI dice que un contenedor sano en local que no se alcanza desde afuera suele necesitar esa corrección. El host default de Uvicorn es 127.0.0.1, y otras máquinas no llegan a esa dirección. Escuchá en 0.0.0.0. El comando de la guía usa ${PORT:-8000}: si PORT está vacío, cae a 8000. La imagen además define ENV PORT=8000. Leé los logs de runtime antes de subir CPU o memoria. Un error de import suele querer decir que la ruta main:app no coincide con el módulo, o que faltó una dependencia en la imagen.
¿Dónde van los secretos y la configuración de FastAPI en producción?
En variables de entorno, fuera del repositorio y fuera de la imagen. La página de settings de FastAPI dice que las claves secretas y las credenciales de la base se leen del entorno. pydantic-settings es opcional: BaseSettings lee esas variables y las valida. Un archivo .env es la forma local de lo mismo, en esa página. No lo commitees y no lo copies a una capa de la imagen. En Unbroker los valores son variables de runtime. Cómo se agrupan está en Variables de entorno y secretos.
¿Cuándo tienen que correr las migraciones de Alembic?
Una vez, como paso propio, con las credenciales de runtime. No mientras se construye la imagen y no desde cada proceso del servidor. La guía de FastAPI pide un paso deliberado de migración de schema y dice que no corras migraciones durante el build. Los conceptos de deploy de FastAPI dicen que un paso previo, como una migración, tiene que correr una sola vez: si corre en paralelo, puede entrar en conflicto. Si el proyecto ya usa Alembic, ese comando es el paso. En Unbroker, los comandos de migración requieren Pro. Qué no deshace un rollback de código está en Migraciones de base de datos en el deploy.
¿Alcanza con BackgroundTasks de FastAPI para un trabajo largo?
Para una tarea chica que puede correr en el mismo proceso después de la respuesta, sí. La página de background tasks de FastAPI las usa cuando el cliente no tiene que esperar, por ejemplo un aviso por email. La misma página dice que un trabajo pesado que no necesita ese proceso va a una herramienta de cola, que puede correr en otros procesos y en otras máquinas. BackgroundTasks no sobreviven al proceso. Si el trabajo tiene que sobrevivir un reinicio, usá un worker y una cola durable. El corte está en Workers en segundo plano y cron.
¿Puedo desplegar FastAPI en el plan Free de Unbroker?
No. El camino documentado es un build de Dockerfile, y los builds de Dockerfile no están en Free. La tabla de planes los marca como no disponibles en Free y disponibles en Pro. La página de precios lista los Dockerfiles con Pro. Esta nota no describe otra forma de correr FastAPI en Free. Pro sale $25 por mes con $25 de crédito de uso. Los pasos están en Desplegar FastAPI y en la guía de FastAPI.
¿Cómo despliego una app FastAPI con Docker Compose?
Tratá el archivo Compose como un inventario, no como una unidad que Unbroker corre. Cuando creás un proyecto podés pegar un archivo Compose, y Unbroker crea un servicio por entrada. Ese camino admite imágenes, builds de repositorio, entorno, depends_on, puertos, comandos y un volumen persistente por servicio. No elige qué es público, dónde viven los datos ni si una base tiene que ser un clúster gestionado. El servicio de FastAPI sigue siendo un Dockerfile que arranca Uvicorn en 0.0.0.0 y en PORT, y los builds de Dockerfile requieren Pro.