Docker Builds with heroku.yml (developer preview)
Last updated 16 July 2018
Table of Contents
heroku.yml is a new manifest for defining your app. This article is specifically about using heroku.yml to build your Dockerfiles - If your app uses buildpacks, learn how to use buildpacks with heroku.yml.
Docker builds with heroku.yml is currently in developer preview. Please email firstname.lastname@example.org to provide feedback.
heroku.yml allows you to:
- Define your app in a singular manifest
- Specify add-ons and config vars to create at app provisioning
- Build your Docker images on Heroku
- Take advantage of Review Apps when deploying Docker-based applications
heroku.yml has 4 sections:
setup- Specify the add-ons and config vars you would like created at app provisioning
build- Specify the Dockerfiles to build
release- Specify the release phase tasks to execute
run- Specify process types and the commands to run
Here’s an example illustrating full usage of heroku.yml for Docker builds:
setup: addons: - plan: heroku-postgresql as: DATABASE config: S3_BUCKET: my-example-bucket build: docker: web: Dockerfile worker: worker/Dockerfile config: RAILS_ENV: development FOO: bar release: command: - ./deployment-tasks.sh image: worker run: web: bundle exec puma -C config/puma.rb worker: python myworker.py asset-syncer: command: - python asset-syncer.py image: worker
To get started, create a heroku.yml file and commit it to Git:
$ git add heroku.yml $ git commit -m "Add heroku.yml"
Set the stack of your app to
$ heroku stack:set container
And push your app to Heroku:
$ git push heroku master
Your application will be built with a new build service and Heroku will use the
run command provided in the manifest, rather than your Procfile.
setup: Defining your app’s environment
heroku.yml supports creating add-ons at app provisioning time. To provision an add-on, add it to the
setup: addons: - plan: heroku-postgresql as: DATABASE
as option allows you to attach multiple instances of the same add-on provider with different names.
Setting config vars
heroku.yml supports setting config vars at app provisioning time. To set a config var, add it to the
setup: config: S3_BUCKET: my-example-bucket
build: Defining your build
Specify Dockerfiles using paths relative to heroku.yml:
build: docker: web: Dockerfile worker: worker/Dockerfile
If you do not specify a
run section, the
CMD specified in the Dockerfile is used.
Setting build-time environment variables
The config section of heroku.yml allows you set environment variables available to the build environment:
build: config: RAILS_ENV: development FOO: bar
Variables set in this section will NOT create config variables at runtime. Each build-time environment variable must match an
ARG line in your Dockerfile:
ARG RAILS_ENV=production ARG FOO
release: Release phase
Release phase enables you to run tasks before a new release is deployed to production (e.g., sending CSS/JS/assets to a CDN, priming cache stores, or running database schema migrations).
To define a release phase command, specify a
release section with a
command in your heroku.yml, as well as the
image you would like to use:
build: docker: web: Dockerfile worker: worker/Dockerfile release: image: worker command: - ./deployment-tasks.sh
If you would like to see streaming logs as release phase executes, your Docker image is required to have curl. If your Docker image does not include curl, release phase logs will be available in your application logs. If you’re using Heroku-16 as your base image, curl is included.
run: Defining the process to run
The run section allows you to define the process that you would like Heroku to run when your application is started. If your project also includes a Procfile, the Procfile will be ignored and
run will be used.
run: web: bundle exec puma -C config/puma.rb
To use a specific Docker image for multiple processes, specify it with
build: docker: web: Dockerfile run: web: bundle exec puma -C config/puma.rb worker: command: python myworker.py image: web
If you do not include a
run section in your heroku.yml, the Dockerfile
CMD will be used.
To learn more about the runtime requirements for Docker images, review the Container Registry and Runtime documentation.
Review apps and app.json
Today, when using heroku.yml, an app.json file is still required when using Review Apps. In the future, we envision app.json functionality being included in heroku.yml (i.e., an app.json file is no longer required).
Be sure to set the stack value in your app.json to
Using heroku.yml in your app
After you’ve created a
heroku.yml file in the base directory of your app, install the
heroku-manifest plugin from
beta update channel:
$ heroku update beta $ heroku plugins:install @heroku-cli/plugin-manifest
You can switch back to the stable update stream and remove the plugin at any time:
$ heroku update stable $ heroku plugins:remove manifest
If your app is not yet created, use the
--manifest option to apply
heroku.yml to the newly-created application. If you are updating an existing app, skip this step:
$ heroku create your-app-name --manifest
Remove the Procfile (optional) and commit
heroku.yml to git:
$ rm Procfile $ git rm Procfile $ git add heroku.yml $ git commit -m "Added heroku.yml and removed Procfile"
$ heroku stack:set container
Push the code:
$ git push heroku master
Known issues and limitations
- While Review Apps are currently supported, pipeline promotions are not