The short answer

A Heroku Procfile is a text file that names process types and the command each type runs. web is the only type that receives HTTP, and it has to bind $PORT. release runs before a new release is deployed. Every other name, including worker and clock, is an ordinary process type.

To move Heroku app to containers, give each long-running line its own service. The web command becomes an HTTP service that listens on the platform port and answers a health check. A Heroku Procfile worker line becomes a service with no inbound HTTP. The Heroku release phase becomes a migration command, not a step inside the image build and not a step inside every copy’s startup. Heroku Scheduler becomes a scheduled job, or a clock process you keep running when the schedule is critical. Config vars become environment variables. Buildpacks become a managed build, or a Dockerfile.

This page does not quote Heroku prices. The move, if you have already decided to leave, is Migrate from Heroku. The comparison is the Heroku page. Heroku vs Railway sits with the other comparisons. A Railway repo that carries railway.toml, rather than a Procfile, is mapped in railway.toml, field by field. A Render repo that carries render.yaml is mapped in render.yaml, field by field.

What a Procfile declares

The file is always named Procfile, with no extension, and it lives in the app root. Procfile.txt is not valid. Anywhere else, it does not run. The Procfile is the source for this section.

Each line has this shape:

<process type>: <command>

The process type is an alphanumeric name, such as web, worker, urgentworker, or clock. The command is what every dyno of that type executes on startup. Each dyno belongs to one declared type.

Two names are special. web is the only process type that can receive external HTTP traffic from Heroku’s routers. release is the command that runs during the release phase. No other process type has special properties. A worker line is a name you chose, not a platform feature.

A Procfile is not required for a simple app in most languages Heroku supports. The platform detects the language and creates a default web process type. The same page recommends an explicit file when you want control over the commands. If the app uses heroku.yml as its build manifest, a Procfile is not required. The run section uses the same format, except release.

Heroku starts one web dyno for you. Other process types do not start until you scale them. heroku ps:scale worker=1 is the example on that page. You can scale two worker names independently, for example worker=1 and urgentworker=5.

These lines are the shapes from the Procfile article and the release-phase article, not one sample app:

web: bundle exec rails server -p $PORT
worker: bundle exec rake jobs:work
release: python manage.py migrate

The command may refer to config vars. The page calls $PORT the useful one.

The web process and $PORT

The web command is the HTTP server. On Cedar-generation apps, the dyno manager sets $PORT for a web dyno, and the dyno must bind that port to receive requests. Dyno Startup Behavior says a web dyno must bind its assigned $PORT within 60 seconds of startup. If it does not, the dyno manager terminates it, and the error is an R10 Boot Timeout. Processes may bind other ports before and after that. The same page says a boot timeout tool can raise the limit as a temporary measure, and that the tool exists for Cedar-generation apps and not for Fir-generation apps.

On Fir-generation apps, a web dyno binds IPv6 at [::]:$PORT, with the same 60 second limit.

On the container stack, the rule is the same idea. Container Registry & Runtime says that article applies to Cedar-generation apps. The web process must listen for HTTP on the $PORT Heroku sets. EXPOSE is not respected at runtime. Only HTTP requests are supported. CMD is always executed by a shell, so config vars are available to the process. ENTRYPOINT is optional. A HEALTHCHECK instruction is not supported. The dyno manager checks the health of running containers. That page does not say which path the check requests.

A Rails line passes the port on the command: web: bundle exec rails server -p $PORT. A process that reads the environment itself, such as many Node servers, still has to bind the value Heroku set. Binding a fixed port, or binding only 127.0.0.1, does not receive the router.

Workers

A Heroku Procfile worker line is a process type with no special properties. It does not receive HTTP. It does not start when you deploy. You scale it. Dynos describes worker dynos as the usual place for background jobs, queues, and timed jobs, and says you can have more than one kind.

A clock line is the same kind of declaration. The Procfile article lists a clock as an example of a singleton process. It is not a second scheduler built into the platform. Heroku Scheduler recommends a custom clock process when the schedule is a critical part of the app, because Scheduler execution is not guaranteed.

On a container platform, both of those lines are long-running processes with no inbound HTTP. They are not a second route on the web service. How a consumer differs from a command that starts and exits is Background workers and cron jobs.

The release phase

The Heroku release phase is the release process type. Release Phase says it runs tasks before a new release is deployed. The examples on that page are asset uploads, cache priming, and database schema migrations.

The command runs in a one-off dyno whenever a new release is created, except a release caused by an add-on’s config vars. These events create a release: a successful build, a config var change that is not an add-on config var, a pipeline promotion, a rollback, a release through the platform API, and provisioning an add-on. A rollback is on that list, so the release command runs again on a rollback. App dynos do not boot for the new release until the phase finishes successfully.

If the command exits non-zero, or the dyno manager shuts it down, the new release is not deployed. The current release stays. Heroku sends an email. The phase has a one-hour timeout, and that limit cannot be extended. Heroku marks a release that is still pending as failed after 24 hours. If the release was triggered by a config var change and the command fails, the new config var value remains. heroku releases:retry retries a failed release without a new build.

The dyno filesystem is ephemeral. Files written during the phase are not deployed to the formation. The page says not to use the phase for work that needs that filesystem, and it names asset compilation as build work, not release work.

Several events create a release, so a migration command can run when the schema is already at that version. The page says the script should check before it migrates. Releases can also overlap, and the page recommends an advisory lock for that. A wrapper script has to propagate a non-zero exit. If it does not, the phase can report success because the wrapper itself started. How to write the migration so a code rollback still runs is Database migrations on deploy.

Heroku Scheduler and one-off dynos

Heroku Scheduler is an add-on. It is not a Procfile line. The dashboard lets you run a command every 10 minutes, every hour, or every day, at a time you pick. Daily times are UTC. You can name a process type instead of a command, and Heroku runs that type’s command. Jobs run as one-off dynos and show up in logs as scheduler.X.

Execution is expected, not guaranteed. The article says a job can, rarely, be skipped or run twice. A dyno started by Scheduler does not run longer than its interval. A job set to every 10 minutes is terminated after about 10 minutes. Jitter can make two runs of the same job overlap briefly. The article says anything that takes longer than a couple of minutes should run on a worker dyno, and that a critical schedule should be a custom clock process instead.

If the app deploys with Container Registry, the Scheduler task has to be on the web image. That article says there is no way to pick a non-web image for the task.

One-off dynos are the mechanism Scheduler uses, and they are also what heroku run starts. One-Off Dynos lists migrations, a console, and one-time scripts as the uses. They appear as the process type run. They never receive HTTP. The filesystem is discarded when you disconnect. They do not restart on their own, and they do not restart after a new release. They are not exactly-once: the page says a run can, rarely, be skipped or happen twice.

Most one-off dynos are cycled every 24 hours, so most can run for at most 24 hours. Fir-generation apps can set a flag to skip that daily restart. This page does not name the flag. An attached session has an inactivity timeout: one hour on most Cedar-generation dynos, 15 minutes in Shield Spaces and on Fir. A detached dyno has no connection, so it has no connection timeout. The initial connectivity limit, dyno size, and how many one-off dynos can run at once are on that page’s later sections. This note does not restate the size table.

A command that starts, does the work, and exits is this shape. A process that stays up and waits on a queue is a worker. Those are different services after the move.

Config vars and buildpacks

Config vars are the app’s environment-specific configuration. Configuration and Config Vars says they are exposed to the code as environment variables. In Node, process.env.DATABASE_URL is the example. Setting or removing a config var restarts the app and creates a new release. Values persist across deploys until you change them.

For classic buildpacks, config vars are available at build time and at runtime. For Cloud Native Buildpacks, they are runtime-only unless you enable the Build Time Config Vars lab feature. The combined keys and values cannot exceed 64 KB per app. Keys should be alphanumeric plus underscore, should not start with a digit, should not contain a hyphen, should not start with __, and should not start with HEROKU_ unless the platform set them.

Buildpacks are scripts that turn the repo into something a dyno can run. Heroku’s own set covers Ruby, Python, Java, Clojure, Node.js, Scala, Go, PHP, and .NET. Classic buildpacks, on Cedar, produce a slug. They are not used on Fir. Cloud Native Buildpacks produce an OCI image. Fir apps use those by default. Cedar apps use classic buildpacks by default. You can also deploy Docker images to Cedar instead of pushing code for a buildpack build.

A Procfile to Dockerfile move, on Heroku’s own registry, is one image per process type. heroku container:push web builds the web image. Multiple types use Dockerfile.web and Dockerfile.worker, pushed with heroku container:push --recursive. The release phase is an image named release, and you release it with the web image: heroku container:release web release. The web image listens on $PORT. The worker image does not.

That registry is one vendor’s container path. The split is the same on any container platform: the Procfile command becomes the container start command, and each long-running type becomes its own service.

Procfile line by line

LineWhat Heroku does with itWhat to run instead
web: <command>The only process type that receives HTTP. The web dyno binds $PORT within 60 seconds.An HTTP service. It listens on the platform port and answers a health check.
worker: <command>No special properties. It does not start until you scale it. It does not receive HTTP.A service with no inbound HTTP and no public URL.
release: <command>A one-off dyno before the new release. A non-zero exit leaves the current release. One hour, not extendable.One migration command, outside the image build and outside every copy’s startup.
clock: <command>An ordinary process type. Scheduler’s article recommends a clock when the schedule is critical.A long-running service with no HTTP port, the same shape as a worker.
Heroku SchedulerNot a Procfile line. Every 10 minutes, every hour, or every day, as a one-off dyno. Not guaranteed.A scheduled job: a command that starts, runs, and exits. Or a clock, if the schedule is critical.
heroku runNot a Procfile line. A one-off dyno of type run. It never receives HTTP.A one-off command against that service’s image and variables.
Config varsEnvironment variables. Setting or removing one restarts the app and creates a release.Environment variables on the service. Not in Git.
BuildpacksScripts that produce a slug or an OCI image from the repo.A managed framework build, or a Dockerfile whose start command is the process command.

How this works on Unbroker

Projects and services says to use more than one service when the app has a separate web process, API, worker, or scheduled workload. Each service has its own settings, variables, resources, domains, and deploy history. The docs do not describe importing a Procfile. You copy each command onto the service that should run it.

The web line is a repository service that listens. Deploy a Node.js application says the process must listen on 0.0.0.0 and the supplied PORT, not a hard-coded localhost address. Deployments says a failed health check keeps that revision from being treated as live. On Pro, the Express guide says to set the health-check path to the route you serve. The plans table lists advanced health checks as not available on Free and available on Pro. This page does not state a boot-timeout length.

The worker line is a different service. In Cloud, add a service and select the Worker category. Deploy a background worker says not to create a public web service only so a process with no listener can pass an HTTP health check. A worker has no public URL. Service types says a worker cannot be marked private, because it already has no Service and no public URL, and that image services, workers, and any service with a persistent volume always run one replica. Dockerfile workers still run without a public URL, an inbound service, or an HTTP readiness probe. Worker services are not available on Free and are available on Pro.

The release line is a migration step. The Django guide says to run database migrations once, as a controlled release step, with the runtime credentials. It says to avoid putting migrations in the image build and to avoid running competing migrations in every web process. Infrastructure as code maps a preDeploy field. The IaC page says changing pre-deploy commands rebuilds the service. It does not say when preDeploy runs, or what a failed preDeploy does to the version that is already live. Migration commands require Pro. A post-deploy command is a different hook: Deployments says it runs after the deployment is live, for at most 10 minutes, and a failure leaves the deployment live. The release step is Database migrations on deploy.

Scheduler’s fixed intervals become a scheduled job, and heroku run becomes a one-off command. The plans table lists both as not available on Free and available on Pro. Infrastructure API lists and creates jobs at GET and POST /apps/services/:id/jobs, updates or deletes one at PUT and DELETE /apps/services/:id/jobs/:jobId, and runs one now at POST /apps/services/:id/jobs/:jobId/run. A one-off command is POST /apps/services/:id/commands. The worker guide says a script that processes one item and exits uses a scheduled or one-off flow, not a long-running worker. Those pages do not publish the schedule expression. A Heroku Scheduler alternative on this platform is that job, or a worker you leave running if the schedule has to be a clock. The operational split is Background workers and cron jobs.

Config vars become service variables. Environment variables says they are provided to the runtime and are not committed. When you add or edit one, you select Production, Preview, or All. A service variable overrides a shared project variable with the same key. Shared project variables require Pro. The IaC page lists adding, changing, or removing a service variable as a deploy-triggering change. Configure environment variables and secrets says to redeploy so the running revision uses the new value. How scope and previews work is Environment variables and secrets.

Buildpacks become a framework build or a Dockerfile. Deploy from Git says server projects, including Bun, pnpm, Yarn, and workspaces, default to Railpack, and that a repository Dockerfile is the explicit build. Deploy a Docker container says to choose Dockerfile under Build & deploy and to give a path relative to the root directory. Leave the root directory empty when the Dockerfile needs the whole repository as its build context. The listener binds 0.0.0.0 and the runtime port. EXPOSE by itself does not publish a port. For a worker image, ENTRYPOINT or CMD is the start command. The plans table lists managed Node.js as included on Free, other framework recipes as not available on Free, and Dockerfile builds as not available on Free and available on Pro. What Free can run is a $0 plan for a small backend.

Free is one project, two services, and three deploy requests per UTC day. Each Free service runs one replica, up to 250m CPU and 256 MiB, and sleeps when idle. Pro is $25 a month with $25 of usage credit. The credit resets each billing cycle, does not roll over, and has no cash value. If eligible usage stays under the credit, the monthly charge is still the plan price. If eligible usage is above the credit, only the difference is added. Those terms are on pricing and in Plans.

Checklist

  1. Name the file Procfile, with no extension, in the app root. List every process type.
  2. Treat web as the only HTTP process. On Heroku it binds $PORT within 60 seconds. On Unbroker it listens on 0.0.0.0 and the supplied PORT.
  3. Give each worker its own service. Do not leave it inside the web process. On Heroku it does not start until you scale it.
  4. Move release out of the image build and out of every replica’s startup. On Heroku a non-zero exit leaves the current release in place, and the limit is one hour.
  5. Replace Scheduler with a scheduled job, or with a clock process if the schedule is critical. Scheduler is every 10 minutes, every hour, or every day, and it is not guaranteed.
  6. Keep heroku run as a one-off command. It never receives HTTP.
  7. Copy config vars into service variables. Do not commit them. On Heroku, setting one creates a release.
  8. Pick a managed build or a Dockerfile. On Unbroker, Dockerfile builds, workers, scheduled jobs, one-off commands, and migration commands require Pro.
  9. Point the web service’s health check at a real route on Pro. Do not add a public URL only so a worker can pass an HTTP check.

FAQ

What is a Heroku Procfile?

A text file named Procfile, with no extension, in the app root. Procfile.txt is not valid. Each line is a process type, then a colon, then the command every dyno of that type runs on startup. web is the only type that receives external HTTP. release is the command for the release phase. No other name has special properties. The source is the Procfile article.

Does a Heroku Procfile worker receive HTTP?

No. Only the web process type receives external HTTP from Heroku's routers. A worker is an ordinary process type. Heroku starts one web dyno for you. Other types, including a Heroku Procfile worker line, do not start until you scale them. The same article is the source.

What happens if the Heroku release phase fails?

The new release is not deployed, and the current release stays. That happens when the release command exits non-zero or the dyno manager shuts it down. The phase has a one-hour timeout, and that limit cannot be extended. If the release was caused by a config var change, the new value remains even when the command fails. App dynos do not boot for the new release until the phase finishes successfully. The source is Release Phase.

Is Heroku Scheduler a cron expression?

No. The Scheduler dashboard offers every 10 minutes, every hour, or every day. Each job runs as a one-off dyno. Execution is expected, not guaranteed: a job can rarely be skipped or run twice. A run is stopped after about its interval, so a 10-minute job ends after about 10 minutes, and two runs can overlap briefly. For a critical schedule, that article recommends a custom clock process. A Heroku Scheduler alternative on a container platform is a scheduled job, or that clock. The source is Heroku Scheduler.

How do I turn a Procfile into a Dockerfile?

On Heroku's container registry, which that article limits to Cedar-generation apps, you build one image per process type. Dockerfile.web and Dockerfile.worker are the documented names. The release phase is an image named release. The web process must listen on the $PORT Heroku sets. EXPOSE is not respected at runtime, and CMD runs in a shell so config vars expand. The source is Container Registry & Runtime. On Unbroker, a Dockerfile is selected under Build & deploy, and Dockerfile builds require Pro. The steps are Deploy a Docker container.

Where do Heroku config vars go?

They are environment variables. Heroku exposes them to the process, and setting or removing one restarts the app and creates a release. On Unbroker they are service variables, scoped Production, Preview, or All. Changing a service variable is a deploy-triggering change. Do not commit the values. Heroku's rules are Config Vars. Unbroker's are Environment variables.