Skip to main content

Deploying with Heroku

Heroku is a Platform as a Service (PaaS) designed to handle application deployment in a hands-off way. Heroku supports container deployment of Docker images, a natural fit for Backstage.

Configuring the CLI

First, install the heroku-cli and login:

$ heroku login

If you have not yet created a project through the Heroku interface, you can create it through the CLI.

$ heroku create <your-app>

You might also need to set your Heroku app's stack to container:

$ heroku stack:set container -a <your-app>

Configuring your app-config.yaml:

# Should be the same as backend.baseUrl when using the `app-backend` plugin
baseUrl: https://<your-app>

baseUrl: https://<your-app>
$env: PORT
# The $PORT environment variable is a feature of Heroku

Make sure your file is being copied into your container in the Dockerfile.

Before building the Docker image, run the backstage host build commands. They must be run whenever you are going to publish a new image.

Heroku runs a container registry on To push Backstage Docker images, log in to the container registry also:

$ heroku container:login

Push and deploy a Docker image

Now we can push a Backstage Docker image to Heroku's container registry and release it to the web worker:

$ docker image build . -f packages/backend/Dockerfile --tag<your-app>/web

$ docker push<your-app>/web

$ heroku container:release web -a <your-app>

Now you should have Backstage up and running! 🎉