Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 37 ยท Deployment and Releases

Container Deploys with Docker

Deploy Docker images to Heroku two ways: build from a Dockerfile with heroku.yml, or push a prebuilt image with the container registry, and avoid the common PORT and CMD mistakes.

Buildpacks are convenient, but they only cover what a buildpack knows how to build. If you need a specific system library, a language version nobody ships a buildpack for, or you already package everything as a Docker image, Heroku can run your container instead. You still get dynos, releases, config vars and add-ons; only the way the slug is made changes.

This lesson shows both container workflows, what Docker images must do to behave on Heroku, and when not to use containers at all.

Two ways to deploy containers

Workflow How it builds Command
Build manifest (heroku.yml) Heroku builds your Dockerfile when you git push git push heroku main
Container Registry You build the image locally or in CI and push it heroku container:push web then heroku container:release web

Both need the app to use the container stack:

CONSOLE
$ heroku stack:set container

Build manifest with heroku.yml

A heroku.yml file in the repository root describes how to build each process type and what to run:

YAML
build:
  docker:
    web: Dockerfile
    worker: Dockerfile.worker
  config:
    RAILS_ENV: production
release:
  image: web
  command:
    - ./bin/migrate
run:
  web: ./bin/serve
  worker: ./bin/work
  • build.docker maps each process type to a Dockerfile.
  • build.config provides build-time arguments.
  • release defines a release phase command and which built image it runs in.
  • run can override the Dockerfile's CMD per process type.

Push with Git as usual. Heroku builds the images from your Dockerfiles, and a release is created.

Container Registry

When you build in CI, or want the exact image you tested, push it directly:

CONSOLE
$ heroku container:login
$ heroku container:push web --app demo-shop
$ heroku container:release web --app demo-shop

container:push builds the Dockerfile in the current folder and uploads the image to Heroku's registry; container:release makes it the running release. Use container:push --recursive with Dockerfile.web, Dockerfile.worker naming to push several process types at once. You can also pull images from your own registry into your build process, but the platform runs images from its own registry.

What your image must do

A container that runs fine locally can still fail on Heroku. Know these rules:

  1. Listen on $PORT. The platform sets PORT at runtime. Hard-coding a port is the number-one failure.
  2. Use shell form if you rely on variable expansion. In a Dockerfile, CMD ["gunicorn", "-b", "0.0.0.0:$PORT", "app:app"] (exec form) does not expand $PORT, because no shell is involved. Write CMD gunicorn -b 0.0.0.0:$PORT app:app (shell form), or CMD ["sh", "-c", "gunicorn -b 0.0.0.0:$PORT app:app"].
  3. Do not rely on root. Heroku runs the container as a non-root user, so files your app writes must be in places any user may write (such as /tmp).
  4. Ignore EXPOSE and VOLUME. Heroku does not use them; volumes do not persist, because the filesystem is ephemeral.
  5. Keep it small. Multi-stage builds and slim base images start faster. Images have a size limit, and large images slow every restart.
  6. Log to stdout/stderr so the platform can collect output.

Containers or buildpacks?

Choose buildpacks when they cover your stack; they are less to maintain, receive security updates through stack upgrades, and build quickly with caching. Choose containers when you need control of the OS packages, a custom runtime, or the exact image from CI. The cost of containers is that you keep the base image updated.

Stand-in: validate a heroku.yml

This stand-in checks a manifest (already parsed into a Python dictionary) against the rules above: every run type must have a Docker build, and release must refer to a built type. It is a teaching validator, not the platform's.

Python Stand-in: check a heroku.yml structure

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in: spot the exec-form PORT bug

The Dockerfile mistake in rule 2 is subtle because the file looks right. This stand-in simulates the difference: shell form lets a shell expand variables, exec form passes the text literally.

Python Stand-in: shell form vs exec form

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The exec form keeps the literal text $PORT, which the server would reject, while the shell and sh -c forms receive the real port.

A minimal working Dockerfile

DOCKERFILE
FROM python:3.13-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD gunicorn -b 0.0.0.0:$PORT app:app

Test it locally by passing the variable yourself: docker run -e PORT=8000 -p 8000:8000 myimage. If it answers on port 8000, it will behave on a dyno.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which command sets an app to run containers?

    The container stack tells Heroku to run Docker images instead of building a slug with buildpacks.
  2. 2. What does heroku container:release do?

    container:push uploads the image and container:release creates a release that runs it.
  3. 3. Why does CMD ["gunicorn", "-b", "0.0.0.0:$PORT", "app:app"] fail?

    Exec form runs the program directly without a shell, so $PORT stays literal. Use shell form or sh -c.
  4. 4. Which Docker instruction does Heroku ignore?

    Heroku assigns the port at runtime through PORT and does not use EXPOSE or VOLUME.
  5. 5. When are buildpacks usually a better choice than containers?

    Buildpack apps get stack security updates and cached builds without you maintaining a base image.

Summary

  • Set the container stack, then deploy either by heroku.yml and git push, or by heroku container:push and container:release.
  • Images must listen on $PORT, tolerate a non-root user and log to stdout.
  • Use shell form or sh -c when a command needs variable expansion.
  • Prefer buildpacks unless you need control that only a container provides.

Next: Config vars