Deploying with Heroku

Heroku is a Platform as a Service (PaaS) designed to simplify application deployment.

Create App

Starting with an existing Backstage app or follow the getting started guide to create a new one.

Install the Heroku CLI and create a new Heroku app:

cd your-app/
heroku apps:create <your-app>

Domain

Get Heroku app URL:

heroku domains -a <your-app>
<your-app-123>.herokuapp.com

The core app-backend plugin allows a single Heroku app to serve the frontend and backend. To make this work you need to update the baseUrl and port in app-config.production.yaml:

app:
  baseUrl: https://<your-app-123>.herokuapp.com

backend:
  baseUrl: https://<your-app-123>.herokuapp.com
  listen:
    port:
      $env: PORT
      # The $PORT environment variable is a feature of Heroku
      # https://devcenter.heroku.com/articles/dynos#web-dynos

Build Script

Add a build script in package.json to compile frontend during deployment:

"scripts": {
  "build": "yarn build:backend --config ../../app-config.yaml --config ../../app-config.production.yaml"

Start Command

Create a Procfile in the app's root:

echo "web: yarn workspace backend start --config ../../app-config.yaml --config ../../app-config.production.yaml" > Procfile

Database

Provision a Heroku Postgres database:

heroku addons:create heroku-postgresql -a <your-app>

Update database in app-config.production.yaml:

backend:
  database:
    client: pg
    pluginDivisionMode: schema
    ensureExists: false
    ensureSchemaExists: true
    connection: ${DATABASE_URL}

Allow postgres self-signed certificates:

heroku config:set PGSSLMODE=no-verify -a <your-app>

Deployment

Commit changes and push to Heroku to build and deploy:

git add Procfile && git commit -am "configure heroku"
git push heroku main

View the app in the browser:

heroku open -a <your-app>

View logs:

heroku logs -a <your-app>

Docker

As an alternative to git deploys, Heroku also supports container images.

Login to Heroku's container registry:

heroku container:login

Configure the Heroku app to run a container image:

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

Locally run the host build commands, they must be run whenever you are going to publish a new image:

yarn install --immutable
yarn tsc
yarn build:backend --config ../../app-config.yaml --config ../../app-config.production.yaml

Build, push, and release the container image to the web dyno:

docker image build . -f packages/backend/Dockerfile --tag registry.heroku.com/<your-app>/web
docker push registry.heroku.com/<your-app>/web
heroku container:release web -a <your-app>