Skip to main content
By default, we build your app without a Dockerfile. Use your own Dockerfile when you need something automatic detection can’t do, such as system packages, custom build stages, an unusual toolchain, or full control of the image.

​
Switch an environment to a Dockerfile

  1. Open the , go to App settings > Build, and find the Dockerfile row.
  2. Pick a Dockerfile from the list of ones we found in your repository, or type its path. The path is relative to the root directory and can be 1 to 500 characters. If the file isn’t on the tracked branch, you’ll see “File not found on this branch”.
  3. Deploy. The setting applies from the next deployment.
With the API, set dockerfile on environments.updateSettings. Production and preview have separate build settings, so one can use a Dockerfile while the other builds automatically. The dashboard’s Build page saves to both environments, so set a different value per environment with the API. To go back to automatic builds, choose Automatic (no Dockerfile) in the dashboard, or set dockerfile to null in the API.

​
Set the build context

The root directory is the build context. COPY and ADD paths, and the Dockerfile path, are resolved from it. The default . is the repository root. For a service in services/api, you have two options:
  • Set the root directory to services/api and the Dockerfile path to Dockerfile.
  • Keep the root at . and set the Dockerfile path to services/api/Dockerfile, if the build needs files from elsewhere in the repository.
The root directory must be a relative path like services/api. It can’t start with / or ./, or contain .., backslashes, or spaces.

​
What your container must do

  • Listen on PORT. We set this environment variable to the environment’s port (8080 by default), and it overrides any ENV PORT in your image.
  • Exit cleanly on the shutdown signal, SIGTERM unless you change it, so instances can drain when they’re replaced.
  • Keep local writes under 128 MiB. That’s the cap on the container’s own filesystem. Use the optional disk at /data for anything larger.
If your image’s default command isn’t what you want, set the Start command in runtime settings instead of keeping a second Dockerfile.

​
Why your Dockerfile build failed

A failed build ends the deployment as failed with the code build_failed. The deployment page shows a plain message for common causes, with the full build log underneath: Errors we don’t recognize show the raw build error. If a RUN step in your Dockerfile clones another private repository, it gets a 404 from GitHub. The build has read access only to the repository being built and its private submodules. Use a submodule, vendor the dependency, or fetch it with credentials passed as build-time secrets.

​
Next steps

Build-time secrets

Mount your environment variables into RUN steps safely.

Runtime settings

Port, command, shutdown signal, CPU, memory, and disk.
Last modified on October 22, 2026