La respuesta corta
Un Procfile de Heroku es un archivo de texto que nombra tipos de proceso y el comando que corre cada uno. web es el único que recibe HTTP, y tiene que atarse a $PORT. release corre antes de que se despliegue un release nuevo. Cualquier otro nombre, worker y clock incluidos, es un tipo común.
Para pasar la app a contenedores, cada línea que se queda viva va a su propio servicio. El comando web pasa a ser un servicio HTTP que escucha en el puerto de la plataforma y responde un health check. Una línea worker pasa a ser un servicio sin HTTP de entrada. El release phase Heroku pasa a ser un comando de migración: no va dentro del build de la imagen y no va en el arranque de cada copia. Heroku Scheduler pasa a ser un job programado, o un proceso clock que dejás corriendo si el horario es crítico. Las config vars pasan a ser variables de entorno. Los buildpacks pasan a ser un build gestionado, o un Dockerfile.
Esta nota no copia precios de Heroku. Si ya decidiste irte, el traslado es Migrar de Heroku. La comparación está en la página de Heroku. Heroku vs Railway queda con el resto de las comparaciones. Un repo de Railway que trae railway.toml, en lugar de un Procfile, está mapeado en railway.toml, campo por campo. Un repo de Render que trae render.yaml está mapeado en render.yaml, campo por campo.
Qué declara un Procfile
El archivo se llama siempre Procfile, sin extensión, y vive en la raíz de la app. Procfile.txt no es válido. En otra carpeta, no corre. El Procfile es la fuente de esta sección.
Cada línea tiene esta forma:
<process type>: <command>
El tipo de proceso es un nombre alfanumérico, como web, worker, urgentworker o clock. El comando es lo que ejecuta cada dyno de ese tipo al arrancar. Cada dyno pertenece a un tipo declarado.
Hay dos nombres especiales. web es el único que puede recibir tráfico HTTP externo de los routers de Heroku. release es el comando del release phase. Ningún otro tipo tiene propiedades especiales. Una línea worker es un nombre que elegiste, no una función de la plataforma.
Un Procfile no hace falta para una app simple en la mayoría de los lenguajes que Heroku soporta. La plataforma detecta el lenguaje y crea un tipo web por defecto. La misma página recomienda un archivo explícito cuando querés controlar los comandos. Si la app usa heroku.yml como manifiesto de build, el Procfile no hace falta. La sección run usa el mismo formato, salvo release.
Heroku te arranca un dyno web. Los otros tipos no arrancan hasta que los escalás. heroku ps:scale worker=1 es el ejemplo de esa página. Podés escalar dos nombres de worker por separado, por ejemplo worker=1 y urgentworker=5.
Estas líneas son las formas del artículo del Procfile y del de release phase, no una app de ejemplo:
web: bundle exec rails server -p $PORT
worker: bundle exec rake jobs:work
release: python manage.py migrate
El comando puede citar config vars. La página señala $PORT como la útil.
El proceso web y $PORT
El comando web es el servidor HTTP. En apps Cedar, el dyno manager setea $PORT para un dyno web, y el dyno tiene que atarse a ese puerto para recibir pedidos. Dyno Startup Behavior dice que un dyno web tiene que atarse a su $PORT dentro de los 60 segundos de arranque. Si no lo hace, el dyno manager lo termina, y el error es un R10 Boot Timeout. Los procesos pueden atarse a otros puertos antes y después. La misma página dice que una herramienta de boot timeout puede subir el límite como medida temporal, y que esa herramienta existe para apps Cedar y no para apps Fir.
En apps Fir, un dyno web se ata a IPv6 en [::]:$PORT, con el mismo límite de 60 segundos.
En el stack de contenedores, la idea es la misma. Container Registry & Runtime dice que ese artículo aplica a apps Cedar. El proceso web tiene que escuchar HTTP en el $PORT que setea Heroku. EXPOSE no se respeta en runtime. Solo se soportan pedidos HTTP. CMD siempre corre en un shell, así las config vars le llegan al proceso. ENTRYPOINT es opcional. Una instrucción HEALTHCHECK no está soportada. El dyno manager revisa la salud de los contenedores que están corriendo. Esa página no dice qué ruta pide el chequeo.
Una línea de Rails pasa el puerto en el comando: web: bundle exec rails server -p $PORT. Un proceso que lee el entorno por su cuenta, como muchos servidores Node, igual tiene que atarse al valor que setea Heroku. Atarse a un puerto fijo, o solo a 127.0.0.1, no recibe el router.
Workers
Una línea worker del Procfile es un tipo de proceso sin propiedades especiales. No recibe HTTP. No arranca cuando desplegás. Lo escalás. Dynos describe los dynos worker como el lugar habitual de jobs en segundo plano, colas y tareas con horario, y dice que podés tener más de un tipo.
Una línea clock es la misma clase de declaración. El artículo del Procfile pone un clock como ejemplo de proceso singleton. No es un segundo scheduler de la plataforma. Heroku Scheduler recomienda un proceso clock propio cuando el horario es una parte crítica de la app, porque la ejecución de Scheduler no está garantizada.
En una plataforma de contenedores, las dos líneas son procesos que se quedan vivos y no reciben HTTP. No son una segunda ruta del servicio web. En qué se diferencia un consumidor de un comando que arranca y sale está en Workers y tareas cron.
El release phase
El release phase Heroku es el tipo de proceso release. Release Phase dice que corre tareas antes de desplegar un release nuevo. Los ejemplos de esa página son subir assets, preparar caché y migrar el schema de la base.
El comando corre en un dyno de una vez cada vez que se crea un release, salvo un release causado por las config vars de un add-on. Estos eventos crean un release: un build que salió bien, un cambio de config var que no es de un add-on, una promoción de pipeline, un rollback, un release por la API de la plataforma, y provisionar un add-on. Un rollback está en esa lista, así que el comando release vuelve a correr en un rollback. Los dynos de la app no arrancan el release nuevo hasta que el phase termina bien.
Si el comando sale con un estado distinto de cero, o el dyno manager lo corta, el release nuevo no se despliega. El release actual sigue. Heroku manda un email. El phase tiene un timeout de una hora y ese límite no se extiende. Heroku marca como fallido un release que sigue pendiente a las 24 horas. Si el release vino de un cambio de config var y el comando falla, el valor nuevo de la config var queda. heroku releases:retry reintenta un release fallido sin un build nuevo.
El filesystem del dyno es efímero. Los archivos que se escriben durante el phase no se despliegan a la formación. La página dice que no uses el phase para un trabajo que necesite ese filesystem, y nombra la compilación de assets como trabajo de build, no de release.
Varios eventos crean un release, así que un comando de migración puede correr cuando el schema ya está en esa versión. La página dice que el script tiene que chequear antes de migrar. Los releases también pueden pisarse, y la página recomienda un advisory lock para eso. Un script contenedor tiene que propagar una salida distinta de cero. Si no lo hace, el phase puede figurar como exitoso porque el contenedor arrancó. Cómo escribir la migración para que un rollback de código siga corriendo está en Migraciones de base de datos en el deploy.
Heroku Scheduler y dynos de una vez
Heroku Scheduler es un add-on. No es una línea del Procfile. El panel te deja correr un comando cada 10 minutos, cada hora o cada día, a la hora que elijas. Los horarios diarios están en UTC. Podés nombrar un tipo de proceso en lugar de un comando, y Heroku corre el comando de ese tipo. Los jobs corren como dynos de una vez y aparecen en los logs como scheduler.X.
La ejecución se espera, no se garantiza. El artículo dice que un job puede, rara vez, saltearse o correr dos veces. Un dyno que arranca Scheduler no corre más que su intervalo. Un job puesto cada 10 minutos se termina a los 10 minutos, más o menos. El jitter puede hacer que dos corridas del mismo job se pisen un momento. El artículo dice que lo que tarda más que un par de minutos debería correr en un dyno worker, y que un horario crítico debería ser un proceso clock propio.
Si la app se despliega con Container Registry, la tarea de Scheduler tiene que estar en la imagen web. Ese artículo dice que no hay forma de elegir una imagen que no sea web para la tarea.
Los dynos de una vez son el mecanismo que usa Scheduler, y también lo que arranca heroku run. One-Off Dynos lista migraciones, una consola y scripts de una sola vez como usos. Aparecen como el tipo de proceso run. Nunca reciben HTTP. El filesystem se descarta cuando te desconectás. No se reinician solos, y no se reinician después de un release nuevo. No son exactamente una vez: la página dice que una corrida puede, rara vez, saltearse o pasar dos veces.
La mayoría de los dynos de una vez se reciclan cada 24 horas, así que la mayoría puede correr como máximo 24 horas. Las apps Fir pueden setear un flag para saltear ese reinicio diario. Esta nota no nombra el flag. Una sesión adjunta tiene un timeout de inactividad: una hora en la mayoría de los dynos Cedar, 15 minutos en Shield Spaces y en Fir. Un dyno detached no tiene conexión, así que no tiene timeout de conexión. El límite de conexión inicial, el tamaño del dyno y cuántos dynos de una vez pueden correr juntos están en secciones posteriores de esa página. Esta nota no repite la tabla de tamaños.
Un comando que arranca, hace el trabajo y sale es esta forma. Un proceso que se queda vivo y espera una cola es un worker. Después de la mudanza son servicios distintos.
Config vars y buildpacks
Las config vars son la configuración que cambia según el entorno. Configuration and Config Vars dice que se exponen al código como variables de entorno. En Node, process.env.DATABASE_URL es el ejemplo. Crear o borrar una config var reinicia la app y crea un release nuevo. Los valores persisten entre deploys hasta que los cambiás.
Con buildpacks clásicos, las config vars están en el build y en runtime. Con Cloud Native Buildpacks, son solo de runtime, salvo que actives la feature de laboratorio Build Time Config Vars. La suma de claves y valores no puede pasar de 64 KB por app. Las claves deberían ser alfanuméricas más guion bajo, no deberían empezar con un dígito, no deberían tener un guion, no deberían empezar con __ y no deberían empezar con HEROKU_ salvo que las haya seteado la plataforma.
Los buildpacks son scripts que convierten el repo en algo que un dyno puede correr. El set de Heroku cubre Ruby, Python, Java, Clojure, Node.js, Scala, Go, PHP y .NET. Los buildpacks clásicos, en Cedar, producen un slug. En Fir no se usan. Los Cloud Native Buildpacks producen una imagen OCI. Las apps Fir los usan por defecto. Las apps Cedar usan buildpacks clásicos por defecto. También podés desplegar imágenes Docker en Cedar en lugar de pushear código para un build de buildpack.
Pasar de Procfile a Dockerfile, en el registry de Heroku, es una imagen por tipo de proceso. heroku container:push web construye la imagen web. Varios tipos usan Dockerfile.web y Dockerfile.worker, y se pushean con heroku container:push --recursive. El release phase es una imagen llamada release, y la liberás junto con la imagen web: heroku container:release web release. La imagen web escucha en $PORT. La imagen worker no.
Ese registry es el camino de contenedores de un proveedor. El corte es el mismo en cualquier plataforma de contenedores: el comando del Procfile pasa a ser el comando de arranque del contenedor, y cada tipo que se queda vivo pasa a ser su propio servicio.
El Procfile, línea por línea
| Línea | Qué hace Heroku | Qué correr en su lugar |
|---|---|---|
web: <command> | El único tipo que recibe HTTP. El dyno web se ata a $PORT en 60 segundos. | Un servicio HTTP. Escucha en el puerto de la plataforma y responde un health check. |
worker: <command> | Sin propiedades especiales. No arranca hasta que lo escalás. No recibe HTTP. | Un servicio sin HTTP de entrada y sin URL pública. |
release: <command> | Un dyno de una vez antes del release nuevo. Una salida distinta de cero deja el release actual. Una hora, sin extender. | Un comando de migración, fuera del build de la imagen y fuera del arranque de cada copia. |
clock: <command> | Un tipo común. El artículo de Scheduler recomienda un clock si el horario es crítico. | Un servicio de larga duración sin puerto HTTP, la misma forma que un worker. |
| Heroku Scheduler | No es una línea del Procfile. Cada 10 minutos, cada hora o cada día, como dyno de una vez. No está garantizado. | Un job programado: un comando que arranca, corre y sale. O un clock, si el horario es crítico. |
heroku run | No es una línea del Procfile. Un dyno de una vez de tipo run. Nunca recibe HTTP. | Un comando de una vez contra la imagen y las variables de ese servicio. |
| Config vars | Variables de entorno. Crear o borrar una reinicia la app y crea un release. | Variables de entorno en el servicio. No en Git. |
| Buildpacks | Scripts que producen un slug o una imagen OCI a partir del repo. | Un build de framework gestionado, o un Dockerfile cuyo comando de arranque es el del proceso. |
Cómo funciona en Unbroker
Proyectos y servicios dice que uses más de un servicio cuando la app tiene un proceso web, una API, un worker o una carga programada por separado. Cada servicio tiene su configuración, sus variables, sus recursos, sus dominios y su historial de deploys. Los docs no describen una importación de Procfile. Copiás cada comando al servicio que lo tiene que correr.
La línea web es un servicio de repositorio que escucha. Desplegar una aplicación Node.js dice que el proceso tiene que escuchar en 0.0.0.0 y en el PORT que le llega, no en un localhost fijo. Deployments dice que un health check fallido impide tratar esa revisión como live. En Pro, la guía de Express dice que configures la ruta del health check para que coincida con la ruta que servís. La tabla de planes marca los health checks avanzados como no disponibles en Free y disponibles en Pro. Esta nota no dice cuánto puede tardar el arranque.
La línea worker es otro servicio. En Cloud, agregá un servicio y elegí la categoría Worker. Desplegar un worker en segundo plano dice que no crees un servicio web público solo para que un proceso sin listener pase un health check HTTP. Un worker no tiene URL pública. Tipos de servicio dice que un worker no se puede marcar como privado, porque ya no tiene Service ni URL pública, y que las imágenes, los workers y cualquier servicio con volumen persistente corren siempre una réplica. Los workers de Dockerfile igual corren sin URL pública, sin servicio de entrada y sin sonda de readiness HTTP. Los workers no están en Free y sí están en Pro.
La línea release es un paso de migración. La guía de Django dice que corras las migraciones de base una vez, como paso de release controlado, con las credenciales de runtime. Dice que evites ponerlas en el build de la imagen y que evites correr migraciones en competencia en cada proceso web. La infraestructura como código mapea un campo preDeploy. La página de IaC dice que cambiar los comandos pre-deploy reconstruye el servicio. No dice cuándo corre preDeploy, ni qué le hace un preDeploy fallido a la versión que ya está live. Los comandos de migración piden Pro. Un comando post-deploy es otro gancho: Deployments dice que corre después de que el deployment está live, como máximo 10 minutos, y un fallo deja el deployment live. El paso de release está en Migraciones de base de datos en el deploy.
Los intervalos fijos de Scheduler pasan a ser un job programado, y heroku run pasa a ser un comando de una vez. La tabla de planes lista los dos como no disponibles en Free y disponibles en Pro. Infrastructure API lista y crea jobs en GET y POST /apps/services/:id/jobs, actualiza o borra uno en PUT y DELETE /apps/services/:id/jobs/:jobId, y corre uno ahora en POST /apps/services/:id/jobs/:jobId/run. Un comando de una vez es POST /apps/services/:id/commands. La guía de workers dice que un script que procesa un ítem y sale usa un flujo programado o de una vez, no un worker de larga duración. Esas páginas no publican la expresión del horario. La diferencia operativa está en Workers y tareas cron.
Las config vars pasan a ser variables del servicio. Variables de entorno dice que se le dan al runtime y que no se commitean. Cuando agregás o editás una, elegís Production, Preview o All. Una variable del servicio pisa una variable compartida del proyecto con la misma clave. Las variables compartidas del proyecto piden Pro. La página de IaC lista agregar, cambiar o borrar una variable del servicio como un cambio que dispara un deploy. Configurar variables de entorno y secretos dice que redesplegués para que la revisión que está corriendo use el valor nuevo. Cómo funcionan el alcance y los previews está en Variables de entorno y secretos.
Los buildpacks pasan a ser un build de framework o un Dockerfile. Deploy from Git dice que los proyectos de servidor, incluidos Bun, pnpm, Yarn y los workspaces, usan Railpack por defecto, y que un Dockerfile del repositorio es el build explícito. Desplegar un contenedor Docker dice que elijas Dockerfile en Build & deploy y que pases una ruta relativa al directorio raíz. Dejá el directorio raíz vacío cuando el Dockerfile necesita todo el repositorio como contexto de build. El listener se ata a 0.0.0.0 y al puerto de runtime. EXPOSE por sí solo no publica un puerto. En una imagen worker, ENTRYPOINT o CMD es el comando de arranque. La tabla de planes marca Node.js gestionado como incluido en Free, las otras recetas de framework como no disponibles en Free, y los builds de Dockerfile como no disponibles en Free y disponibles en Pro. Lo que Free puede correr está en un plan de $0 para un backend chico.
Free es un proyecto, dos servicios y tres pedidos de deploy por día UTC. Cada servicio Free corre una réplica, hasta 250m de CPU y 256 MiB, y se duerme cuando está idle. Pro sale $25 por mes con $25 de crédito de uso. El crédito se reinicia en cada ciclo de facturación, no se acumula y no tiene valor en efectivo. Si el uso elegible queda bajo el crédito, el cargo mensual sigue siendo el precio del plan. Si el uso elegible lo pasa, solo se suma la diferencia. Esos términos están en precios y en Plans.
Checklist
- Nombrá el archivo
Procfile, sin extensión, en la raíz de la app. Listá cada tipo de proceso. - Tratá
webcomo el único proceso HTTP. En Heroku se ata a$PORTen 60 segundos. En Unbroker escucha en0.0.0.0y en elPORTque le llega. - Dale a cada worker su propio servicio. No lo dejes adentro del proceso web. En Heroku no arranca hasta que lo escalás.
- Sacá
releasedel build de la imagen y del arranque de cada réplica. En Heroku una salida distinta de cero deja el release actual, y el límite es una hora. - Reemplazá Scheduler por un job programado, o por un proceso clock si el horario es crítico. Scheduler es cada 10 minutos, cada hora o cada día, y no está garantizado.
- Dejá
heroku runcomo un comando de una vez. Nunca recibe HTTP. - Copiá las config vars a variables del servicio. No las subas a Git. En Heroku, setear una crea un release.
- Elegí un build gestionado o un Dockerfile. En Unbroker, los builds de Dockerfile, los workers, los jobs programados, los comandos de una vez y los comandos de migración piden Pro.
- Apuntá el health check del servicio web a una ruta real en Pro. No agregues una URL pública solo para que un worker pase un chequeo HTTP.
Preguntas frecuentes
¿Qué es un Procfile de Heroku?
Un archivo de texto que se llama Procfile, sin extensión, en la raíz de la app. Procfile.txt no vale. Cada línea es un tipo de proceso, dos puntos, y el comando que corre cada dyno de ese tipo al arrancar. web es el único que recibe HTTP de afuera. release es el comando del release phase. Ningún otro nombre tiene propiedades especiales. La fuente es el artículo del Procfile.
¿Un worker del Procfile de Heroku recibe HTTP?
No. Solo el tipo web recibe HTTP externo de los routers de Heroku. Un worker es un tipo común. Heroku te arranca un dyno web. Los demás, incluida una línea worker, no arrancan hasta que los escalás. La fuente es el mismo artículo.
¿Qué pasa si falla el release phase de Heroku?
El release nuevo no se despliega y el actual sigue. Pasa si el comando sale con un estado distinto de cero, o si el dyno manager lo corta. El phase tiene un timeout de una hora y ese límite no se extiende. Si el release vino de un cambio de config var, el valor nuevo queda igual aunque el comando falle. Los dynos de la app no arrancan el release nuevo hasta que el phase termina bien. La fuente es Release Phase.
¿Heroku Scheduler es una expresión cron?
No. El panel ofrece cada 10 minutos, cada hora o cada día. Cada job corre como dyno de una vez. La ejecución se espera, no se garantiza: un job puede, rara vez, saltearse o correr dos veces. Una corrida se corta más o menos al cumplir su intervalo, así que un job de 10 minutos termina a los 10 minutos, y dos corridas pueden pisarse un momento. Si el horario es crítico, ese artículo recomienda un proceso clock propio. La fuente es Heroku Scheduler.
¿Cómo paso de un Procfile a un Dockerfile?
En el container registry de Heroku, que ese artículo limita a apps Cedar, armás una imagen por tipo de proceso. Dockerfile.web y Dockerfile.worker son los nombres que documenta. El release phase es una imagen llamada release. El proceso web tiene que escuchar en el $PORT que setea Heroku. EXPOSE no se respeta en runtime, y CMD corre en un shell para que entren las config vars. La fuente es Container Registry & Runtime. En Unbroker, el Dockerfile se elige en Build & deploy, y los builds de Dockerfile piden Pro. Los pasos están en Desplegar un contenedor Docker.
¿Adónde van las config vars de Heroku?
Son variables de entorno. Heroku se las expone al proceso, y crear o borrar una reinicia la app y crea un release. En Unbroker son variables del servicio, con alcance Production, Preview o All. Cambiar una variable del servicio dispara un deploy. No las subas a Git. Las reglas de Heroku están en Config Vars. Las de Unbroker, en Variables de entorno.