From 92583daf57de6cb64b0ed889deba220c66b933c7 Mon Sep 17 00:00:00 2001 From: Chap Ambrose Date: Thu, 27 Jun 2024 16:43:38 -0500 Subject: [PATCH 1/9] Update heroku deploy docs Signed-off-by: Chap Ambrose --- docs/deployment/heroku.md | 99 ++++++++++++++++++++++++++------------- 1 file changed, 66 insertions(+), 33 deletions(-) diff --git a/docs/deployment/heroku.md b/docs/deployment/heroku.md index 1545c34733..a70ff66ca5 100644 --- a/docs/deployment/heroku.md +++ b/docs/deployment/heroku.md @@ -5,40 +5,40 @@ sidebar_label: Heroku description: How to deploy Backstage to 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. +Heroku is a Platform as a Service (PaaS) designed to simplify application deployment. -## Configuring the CLI +## Create App -First, install the -[heroku-cli](https://devcenter.heroku.com/articles/heroku-cli) and login: +Start with an exisiting Backstage app or follow the [getting started guide](https://backstage.io/docs/getting-started/) to create a new one: ```shell -$ heroku login +$ npx @backstage/create-app@latest + Enter a name ``` -If you have not yet created a project through the Heroku interface, you can create it through the CLI. +Install the +[Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) and create a new Heroku app: ```shell -$ heroku create +$ cd your-app/ +$ heroku apps:create ``` -You _might_ also need to set your Heroku app's stack to `container`: +## Domain -```bash -$ heroku stack:set container -a +Get Heroku app URL: +```shell +$ heroku domains -a +.herokuapp.com ``` -Configuring your `app-config.yaml`: - +Update `baseUrl` and `port` in `app-config.yaml`. The core [app-backend plugin](https://www.npmjs.com/package/@backstage/plugin-app-backend) allows a single Heroku app to serve the frontend and backend: ```yaml app: - # Should be the same as backend.baseUrl when using the `app-backend` plugin - baseUrl: https://.herokuapp.com + baseUrl: https://.herokuapp.com backend: - baseUrl: https://.herokuapp.com + baseUrl: https://.herokuapp.com listen: port: $env: PORT @@ -46,28 +46,61 @@ backend: # https://devcenter.heroku.com/articles/dynos#web-dynos ``` -> Make sure your file is being copied into your container in the `Dockerfile`. +## Build Script -Before building the Docker image, run the [backstage host build commands](https://backstage.io/docs/deployment/docker#host-build). They must be run whenever you are going to publish a new image. +Add a build script in `package.json` to compile frontend during deployment: +```json +"scripts": { + "build": "yarn build:backend --config ../../app-config.yaml" +``` -Heroku runs a container registry on `registry.heroku.com`. To push Backstage -Docker images, log in to the container registry also: +## Start Command + +Create a [Procfile](https://devcenter.heroku.com/articles/procfile) in the app's root: +```shell +$ echo "web: yarn workspace backend start --config ../../app-config.yaml" > Procfile +``` + +## Database + +Provision a [Heroku Postgres](https://elements.heroku.com/addons/heroku-postgresql) database: +```shell +$ heroku addons:create heroku-postgresql -a +``` + +Update `database` in `app-config.yaml`: +```yaml +backend: + database: + client: pg + pluginDivisionMode: schema + ensureExists: false + ensureSchemaExists: true + connection: ${DATABASE_URL} +``` + +Allow postgres self-signed certificates: +```shell +$ heroku config:set PGSSLMODE=no-verify -a +``` + +## Deployment + +Commit changes and push to Heroku to build and deploy: ```shell -$ heroku container:login +$ git add Procfile && git commit -am "configure heroku" +$ git push heroku main ``` -## Push and deploy a Docker image +View the app in the browser: -Now we can push a Backstage [Docker image](docker.md) to Heroku's container -registry and release it to the `web` worker: - -```bash -$ docker image build . -f packages/backend/Dockerfile --tag registry.heroku.com//web - -$ docker push registry.heroku.com//web - -$ heroku container:release web -a +```shell +$ heroku open -a ``` -Now you should have Backstage up and running! 🎉 +View logs: + +```shell +$ heroku heroku -a +``` From bc2700cbf962e3f3a4554d664a193943224b3f27 Mon Sep 17 00:00:00 2001 From: Chap Ambrose Date: Mon, 8 Jul 2024 08:26:47 -0500 Subject: [PATCH 2/9] recommend updating config in app-config.production.yaml Co-authored-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com> Signed-off-by: Chap Ambrose --- docs/deployment/heroku.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/deployment/heroku.md b/docs/deployment/heroku.md index a70ff66ca5..23dff683f8 100644 --- a/docs/deployment/heroku.md +++ b/docs/deployment/heroku.md @@ -32,7 +32,7 @@ $ heroku domains -a .herokuapp.com ``` -Update `baseUrl` and `port` in `app-config.yaml`. The core [app-backend plugin](https://www.npmjs.com/package/@backstage/plugin-app-backend) allows a single Heroku app to serve the frontend and backend: +The core [app-backend plugin](https://www.npmjs.com/package/@backstage/plugin-app-backend) 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`: ```yaml app: baseUrl: https://.herokuapp.com From fb6a5d5f6ba90edb6152c20d4c111b93a9182d16 Mon Sep 17 00:00:00 2001 From: Chap Ambrose Date: Mon, 8 Jul 2024 08:27:20 -0500 Subject: [PATCH 3/9] Typo in docs Co-authored-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com> Signed-off-by: Chap Ambrose --- docs/deployment/heroku.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/deployment/heroku.md b/docs/deployment/heroku.md index 23dff683f8..5e6eb59a82 100644 --- a/docs/deployment/heroku.md +++ b/docs/deployment/heroku.md @@ -9,7 +9,7 @@ Heroku is a Platform as a Service (PaaS) designed to simplify application deploy ## Create App -Start with an exisiting Backstage app or follow the [getting started guide](https://backstage.io/docs/getting-started/) to create a new one: +Starting with an existing Backstage app or follow the [getting started guide](https://backstage.io/docs/getting-started/) to create a new one: ```shell $ npx @backstage/create-app@latest From 6b56a1921925517006e8cbdecffccc3f74814916 Mon Sep 17 00:00:00 2001 From: Chap Ambrose Date: Mon, 8 Jul 2024 08:27:45 -0500 Subject: [PATCH 4/9] add app-config.production to build script Co-authored-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com> Signed-off-by: Chap Ambrose --- docs/deployment/heroku.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/deployment/heroku.md b/docs/deployment/heroku.md index 5e6eb59a82..c5042c732c 100644 --- a/docs/deployment/heroku.md +++ b/docs/deployment/heroku.md @@ -51,7 +51,7 @@ backend: Add a build script in `package.json` to compile frontend during deployment: ```json "scripts": { - "build": "yarn build:backend --config ../../app-config.yaml" + "build": "yarn build:backend --config ../../app-config.yaml --config app-config.production.yaml" ``` ## Start Command From 32b73f957c7ee8379e190f66640a4a9ec7ced9ab Mon Sep 17 00:00:00 2001 From: Chap Ambrose Date: Mon, 8 Jul 2024 08:32:26 -0500 Subject: [PATCH 5/9] remove command to create new backstage app Signed-off-by: Chap Ambrose --- docs/deployment/heroku.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/docs/deployment/heroku.md b/docs/deployment/heroku.md index c5042c732c..9629dbb212 100644 --- a/docs/deployment/heroku.md +++ b/docs/deployment/heroku.md @@ -9,12 +9,7 @@ Heroku is a Platform as a Service (PaaS) designed to simplify application deploy ## Create App -Starting with an existing Backstage app or follow the [getting started guide](https://backstage.io/docs/getting-started/) to create a new one: - -```shell -$ npx @backstage/create-app@latest - Enter a name -``` +Starting with an existing Backstage app or follow the [getting started guide](https://backstage.io/docs/getting-started/) to create a new one. Install the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) and create a new Heroku app: From e80a94f5c31aad63840c36bf592a072310d787c2 Mon Sep 17 00:00:00 2001 From: Chap Ambrose Date: Mon, 8 Jul 2024 09:50:17 -0500 Subject: [PATCH 6/9] add docker instructions to heroku.md Signed-off-by: Chap Ambrose --- docs/deployment/heroku.md | 36 +++++++++++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/docs/deployment/heroku.md b/docs/deployment/heroku.md index 9629dbb212..8f173578c5 100644 --- a/docs/deployment/heroku.md +++ b/docs/deployment/heroku.md @@ -46,14 +46,14 @@ backend: Add a build script in `package.json` to compile frontend during deployment: ```json "scripts": { - "build": "yarn build:backend --config ../../app-config.yaml --config app-config.production.yaml" + "build": "yarn build:backend --config ../../app-config.yaml --config ../../app-config.production.yaml" ``` ## Start Command Create a [Procfile](https://devcenter.heroku.com/articles/procfile) in the app's root: ```shell -$ echo "web: yarn workspace backend start --config ../../app-config.yaml" > Procfile +$ echo "web: yarn workspace backend start --config ../../app-config.yaml --config ../../app-config.production.yaml" > Procfile ``` ## Database @@ -63,7 +63,7 @@ Provision a [Heroku Postgres](https://elements.heroku.com/addons/heroku-postgres $ heroku addons:create heroku-postgresql -a ``` -Update `database` in `app-config.yaml`: +Update `database` in `app-config.production.yaml`: ```yaml backend: database: @@ -99,3 +99,33 @@ View logs: ```shell $ heroku heroku -a ``` + +## Docker + +As an alternative to git deploys, Heroku also [supports container images](https://devcenter.heroku.com/articles/container-registry-and-runtime). + +Login to Heroku's container registry: + +```shell +$ heroku container:login +``` + +Configure the Heroku app to run a container image: + +```shell +$ heroku stack:set container -a +``` + +Locally run the [host build command](https://backstage.io/docs/deployment/docker/#host-build): +```shell +$ yarn build:backend --config ../../app-config.yaml --config ../../app-config.production.yaml +``` + +Build, push, and release the container image: +```shell +$ docker image build . -f packages/backend/Dockerfile --tag registry.heroku.com//web + +$ docker push registry.heroku.com//web + +$ heroku container:release web -a +``` From dc41795dd508275e8d95a89b81861dd1ea636500 Mon Sep 17 00:00:00 2001 From: Chap Ambrose Date: Mon, 8 Jul 2024 11:15:28 -0500 Subject: [PATCH 7/9] prettier fixes Signed-off-by: Chap Ambrose --- docs/deployment/heroku.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/deployment/heroku.md b/docs/deployment/heroku.md index 8f173578c5..74732bb431 100644 --- a/docs/deployment/heroku.md +++ b/docs/deployment/heroku.md @@ -22,12 +22,14 @@ $ heroku apps:create ## Domain Get Heroku app URL: + ```shell $ heroku domains -a .herokuapp.com ``` The core [app-backend plugin](https://www.npmjs.com/package/@backstage/plugin-app-backend) 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`: + ```yaml app: baseUrl: https://.herokuapp.com @@ -44,6 +46,7 @@ backend: ## Build Script Add a build script in `package.json` to compile frontend during deployment: + ```json "scripts": { "build": "yarn build:backend --config ../../app-config.yaml --config ../../app-config.production.yaml" @@ -52,6 +55,7 @@ Add a build script in `package.json` to compile frontend during deployment: ## Start Command Create a [Procfile](https://devcenter.heroku.com/articles/procfile) in the app's root: + ```shell $ echo "web: yarn workspace backend start --config ../../app-config.yaml --config ../../app-config.production.yaml" > Procfile ``` @@ -59,11 +63,13 @@ $ echo "web: yarn workspace backend start --config ../../app-config.yaml --confi ## Database Provision a [Heroku Postgres](https://elements.heroku.com/addons/heroku-postgresql) database: + ```shell $ heroku addons:create heroku-postgresql -a ``` Update `database` in `app-config.production.yaml`: + ```yaml backend: database: @@ -75,6 +81,7 @@ backend: ``` Allow postgres self-signed certificates: + ```shell $ heroku config:set PGSSLMODE=no-verify -a ``` @@ -117,11 +124,13 @@ $ heroku stack:set container -a ``` Locally run the [host build command](https://backstage.io/docs/deployment/docker/#host-build): + ```shell $ yarn build:backend --config ../../app-config.yaml --config ../../app-config.production.yaml ``` Build, push, and release the container image: + ```shell $ docker image build . -f packages/backend/Dockerfile --tag registry.heroku.com//web From b652b6de1fb647cc8fe65af2f6e6baa71574c9ac Mon Sep 17 00:00:00 2001 From: Chap Ambrose Date: Thu, 11 Jul 2024 08:16:21 -0500 Subject: [PATCH 8/9] add deploy buttuon to heroku.md Signed-off-by: Chap Ambrose --- docs/deployment/heroku.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/deployment/heroku.md b/docs/deployment/heroku.md index 74732bb431..faf1c2106e 100644 --- a/docs/deployment/heroku.md +++ b/docs/deployment/heroku.md @@ -7,6 +7,8 @@ description: How to deploy Backstage to Heroku Heroku is a Platform as a Service (PaaS) designed to simplify application deployment. +[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/chap/backstage-button) + ## Create App Starting with an existing Backstage app or follow the [getting started guide](https://backstage.io/docs/getting-started/) to create a new one. From bf2984369d30ee9b1b18974b85d8edb9ae373834 Mon Sep 17 00:00:00 2001 From: Chap Ambrose Date: Tue, 23 Jul 2024 08:34:14 -0500 Subject: [PATCH 9/9] cleanup heroku.md Signed-off-by: Chap Ambrose --- docs/deployment/heroku.md | 42 +++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 22 deletions(-) diff --git a/docs/deployment/heroku.md b/docs/deployment/heroku.md index faf1c2106e..d285e4b397 100644 --- a/docs/deployment/heroku.md +++ b/docs/deployment/heroku.md @@ -7,8 +7,6 @@ description: How to deploy Backstage to Heroku Heroku is a Platform as a Service (PaaS) designed to simplify application deployment. -[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/chap/backstage-button) - ## Create App Starting with an existing Backstage app or follow the [getting started guide](https://backstage.io/docs/getting-started/) to create a new one. @@ -17,8 +15,8 @@ Install the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) and create a new Heroku app: ```shell -$ cd your-app/ -$ heroku apps:create +cd your-app/ +heroku apps:create ``` ## Domain @@ -26,7 +24,7 @@ $ heroku apps:create Get Heroku app URL: ```shell -$ heroku domains -a +heroku domains -a .herokuapp.com ``` @@ -59,7 +57,7 @@ Add a build script in `package.json` to compile frontend during deployment: Create a [Procfile](https://devcenter.heroku.com/articles/procfile) in the app's root: ```shell -$ echo "web: yarn workspace backend start --config ../../app-config.yaml --config ../../app-config.production.yaml" > Procfile +echo "web: yarn workspace backend start --config ../../app-config.yaml --config ../../app-config.production.yaml" > Procfile ``` ## Database @@ -67,7 +65,7 @@ $ echo "web: yarn workspace backend start --config ../../app-config.yaml --confi Provision a [Heroku Postgres](https://elements.heroku.com/addons/heroku-postgresql) database: ```shell -$ heroku addons:create heroku-postgresql -a +heroku addons:create heroku-postgresql -a ``` Update `database` in `app-config.production.yaml`: @@ -85,7 +83,7 @@ backend: Allow postgres self-signed certificates: ```shell -$ heroku config:set PGSSLMODE=no-verify -a +heroku config:set PGSSLMODE=no-verify -a ``` ## Deployment @@ -93,20 +91,20 @@ $ heroku config:set PGSSLMODE=no-verify -a Commit changes and push to Heroku to build and deploy: ```shell -$ git add Procfile && git commit -am "configure heroku" -$ git push heroku main +git add Procfile && git commit -am "configure heroku" +git push heroku main ``` View the app in the browser: ```shell -$ heroku open -a +heroku open -a ``` View logs: ```shell -$ heroku heroku -a +heroku heroku -a ``` ## Docker @@ -116,27 +114,27 @@ As an alternative to git deploys, Heroku also [supports container images](https: Login to Heroku's container registry: ```shell -$ heroku container:login +heroku container:login ``` Configure the Heroku app to run a container image: ```shell -$ heroku stack:set container -a +heroku stack:set container -a ``` -Locally run the [host build command](https://backstage.io/docs/deployment/docker/#host-build): +Locally run the [host build commands](https://backstage.io/docs/deployment/docker/#host-build), they must be run whenever you are going to publish a new image: ```shell -$ yarn build:backend --config ../../app-config.yaml --config ../../app-config.production.yaml +yarn install --frozen-lockfile +yarn tsc +yarn build:backend --config ../../app-config.yaml --config ../../app-config.production.yaml ``` -Build, push, and release the container image: +Build, push, and release the container image to the `web` dyno: ```shell -$ docker image build . -f packages/backend/Dockerfile --tag registry.heroku.com//web - -$ docker push registry.heroku.com//web - -$ heroku container:release web -a +docker image build . -f packages/backend/Dockerfile --tag registry.heroku.com//web +docker push registry.heroku.com//web +heroku container:release web -a ```