paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 27 Packages Projects Releases Wiki Activity

moving docs around, updating deployment overview section to point to contrib folder for community deployment methods

Browse Source 
Signed-off-by: Peter Macdonald <macdonald.peter90@gmail.com>
This commit is contained in:
Peter Macdonald
2024-11-18 09:13:42 +01:00
parent 98af3a1e82
commit b5baaf5723
6 changed files with 4 additions and 210 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/deployment/backstage-deploy/aws.md
-182
View File
@@ -1,182 +0,0 @@
---
id: aws-lightsail
title: Deploying Backstage on AWS Lightsail
sidebar_label: AWS Lightsail
description: How to deploy Backstage on AWS Lightsail
---
> **DISCLAIMER: The `deploy` command is in alpha and still experimental. Do not use the `deploy` command for production deployments.**
Getting started with Backstage often involves setting up an instance on a cloud provider and sharing it with your team so they can experiment. To make this cloud deployment easier, we've built a `deploy` command to stand up a proof-of-concept instance on AWS (using Lightsail).
## What is AWS Lightsail
:::tip
AWS offers a free tier for up to three months on $10 USD/month Container service (Micro -1 node). By default we use the `nano` node, so if you are a new user this approach shouldn't cost you anything. For more information, refer to the [pricing](https://aws.amazon.com/lightsail/pricing/) documentation.
:::
AWS Lightsail offers a simple way to run containers in the cloud. To learn more about AWS Lightsail, please refer to the [official documentation](https://lightsail.aws.amazon.com/ls/docs/en_us/articles/amazon-lightsail-container-services-deployments).
## Creating user in AWS
- Open the AWS console and navigate to the IAM section
- In the left side menu click on `Users` and then click on `Add users`
- Specify a username and then click on `Next`
- Afterwards you can assign permissions, select `Attach policies directly` and then click on `Create policy`.
This should take you to a new window in which you can create a new policy based on `JSON`.
Copy over the following:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"ecr:DescribeImageReplicationStatus",
"ecr:ListTagsForResource",
"ecr:UploadLayerPart",
"ecr:BatchGetRepositoryScanningConfiguration",
"ecr:DeleteRepository",
"ecr:GetRegistryScanningConfiguration",
"ecr:CompleteLayerUpload",
"ecr:TagResource",
"ecr:DescribeRepositories",
"ecr:DeleteRepositoryPolicy",
"ecr:BatchCheckLayerAvailability",
"ecr:GetLifecyclePolicy",
"ecr:GetRegistryPolicy",
"ecr:PutLifecyclePolicy",
"ecr:DescribeImageScanFindings",
"ecr:GetLifecyclePolicyPreview",
"ecr:CreateRepository",
"ecr:DescribeRegistry",
"ecr:GetDownloadUrlForLayer",
"ecr:GetAuthorizationToken",
"ecr:DeleteLifecyclePolicy",
"ecr:PutImage",
"ecr:UntagResource",
"ecr:SetRepositoryPolicy",
"ecr:BatchGetImage",
"ecr:InitiateLayerUpload",
"ecr:GetRepositoryPolicy",
"lightsail:CreateContainerService",
"lightsail:GetKeyPair",
"lightsail:GetContainerServiceDeployments",
"lightsail:CreateContainerServiceRegistryLogin",
"lightsail:GetContainerImages",
"lightsail:UntagResource",
"lightsail:RegisterContainerImage",
"lightsail:GetContainerServices",
"lightsail:GetContainerServicePowers",
"lightsail:GetKeyPairs",
"lightsail:CreateContainerServiceDeployment",
"lightsail:GetContainerServiceMetricData",
"lightsail:GetContainerAPIMetadata",
"lightsail:DeleteContainerService",
"lightsail:GetContainerLog",
"lightsail:TagResource"
],
"Resource": "*"
},
{
"Sid": "Statement1",
"Effect": "Allow",
"Action": [],
"Resource": []
}
]
}
```
Then click on `Next` and give the policy a name and a description of your liking. Afterwards, click on `Create policy`.
- Navigate back to the user creation window and press on the refresh button and search for the policy you just created. Now, create the user.
- Now you will be redirected to all users, click on the user you just created and click on `Security credentials`
- Scroll below and click on `Create access key`
- Choose `Command Line Interface (CLI)`
- Now export the following values
```bash
$ export AWS_ACCESS_KEY_ID=... (first value)
$ export AWS_SECRET_ACCESS_KEY=.... (second secret value)
```
## Configuring the Pulumi CLI
Second, install the [Pulumi CLI](https://www.pulumi.com/docs/get-started/install/) - `backstage-deploy` uses it to
simplify the management of cloud resources (Pulumi allows us to simply specify the desired "target cloud state", and
Pulumi will intelligently create/modify/delete resources to reach that state. Nice!).
Then we need to execute the following commands, to set Pulumi up:
:::tip
Make sure to store your passphrase somewhere safe as it is used to encrypt/decrypt your Pulumi config.
:::
```bash
$ pulumi login --local
$ export PULUMI_CONFIG_PASSPHRASE="<your-secret>"
```
By using `pulumi login --local` we are making sure that Pulumi stores our state on the local file disk. The environment variable `PULUMI_CONFIG_PASSPHRASE` is used by Pulumi to generate a unique key for your stack
## Deploying your instance on Lightsail
:::tip
Make sure that [Docker](https://docs.docker.com/) is running on your machine before you start this section.
:::
After you have made your changes to your local instance, it's time to deploy it on Lightsail.
First, we need to configure a new `app-config` file and update the `baseUrl`.
```bash
$ touch app-config.deployment.yaml
```
And then update the file with the following yaml:
```yaml
app:
baseUrl: ${BACKSTAGE_HOST}
backend:
baseUrl: ${BACKSTAGE_HOST}
```
The environment variable `BACKSTAGE_HOST` will be set to the endpoint that AWS Lightsail creates.
Now we can deploy our instance!
```bash
$ npx backstage-deploy aws --stack backstage-poc --create-dockerfile
```
In the first part of the command, we are specifying that we want to deploy our instance on AWS. With the [`--stack`](https://www.pulumi.com/docs/reference/cli/pulumi_stack/) option, we are providing Pulumi a reference to our container deployment. Furthermore, with the `--create-dockerfile` option, there will be a `Dockerfile` and `.dockerignore` created in the root of the project.
After running the command, Pulumi will start creating the following resources for you in AWS:
- ECR Repository
- Lightsail Container Service
- Lightsail Container Service Deployment
- Policy that allows Lightsail to pull from ECR
If it's the first time building the Docker image, it might take a while for everything to be fully provisioned. After the command is finished running, your Backstage instance should be up and running on AWS Lightsail! 🎉
### Cleaning up resources
Cleaning up the resources is also done with the deploy command.
```bash
$ npx backstage-deploy aws --stack backstage-poc --destroy
```
This will delete everything that was originally created by the `deploy` command.
docs/deployment/flightcontrol.md
-231
View File
@@ -1,231 +0,0 @@
---
id: flightcontrol
title: Deploying with Flightcontrol
sidebar_label: AWS Fargate via Flightcontrol
description: Deploying Backstage to AWS Fargate via Flightcontrol
---
This guide explains how to deploy Backstage to [Flightcontrol](https://www.flightcontrol.dev?ref=backstage), a platform that fully automates deployments to Amazon Web Services (AWS). Flightcontrol supports git-driven and image registry deployments.
Before you begin, make sure you have a [Flightcontrol account](https://app.flightcontrol.dev/signup?ref=backstage) and a [GitHub account](https://github.com/login) to follow this guide.
# Creating a Dockerfile and .dockerignore
Once your Flightcontrol account is setup, you will need to prepare a `Dockerfile` and `.dockerignore` to deploy Backstage to your target AWS environment. The standard `Dockerfile` included in the Backstage repository assumes that the `skeleton.tar.gz` and `bundle.tar.gz` already exist. When integrating Flightcontrol directly with a GitHub repository, changes to files within this repository will automatically start a Flightcontrol deployment, unless you have configured deployments via a webhook. Regardless of which method you have chosen, when Flightcontrol starts a deployment process it will pull all files directly from the repository, and not from a GitHub runner or other location. As Flightcontrol does not contain CI steps this results in the zip files having to be committed to the repository in order to be available for the `Dockerfile` to copy.
A simple work around for this is to use a `Dockerfile` with a [multi-stage build](https://docs.docker.com/build/building/multi-stage/). Using this approach we can create our zip files in the first build stage, and copy them into the second stage ready for deployment.
The following two code snippets demonstrate this method. The first block of code is an example of a multi-stage build approach and should be added to a file called `Dockerfile.flightcontrol` in the `packages/backend` directory.
```dockerfile filename="Dockerfile.flightcontrol"
# This dockerfile builds an image for the backend package.
# It should be executed with the root of the repo as docker context.
#
# Before building this image, be sure to have run the following commands in the repo root:
#
# yarn install
# yarn tsc
# yarn build:backend
#
# Once the commands have been run, you can build the image using `yarn build-image`
FROM node:20-bookworm-slim as build
USER node
WORKDIR /app
COPY --chown=node:node . .
RUN yarn install --frozen-lockfile
# tsc outputs type definitions to dist-types/ in the repo root, which are then consumed by the build
RUN yarn tsc
# Build the backend, which bundles it all up into the packages/backend/dist folder.
# The configuration files here should match the one you use inside the Dockerfile below.
RUN yarn build:backend --config ../../app-config.yaml
FROM node:20-bookworm-slim
# Install isolate-vm dependencies, these are needed by the @backstage/plugin-scaffolder-backend.
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
--mount=type=cache,target=/var/lib/apt,sharing=locked \
apt-get update && \
apt-get install -y --no-install-recommends python3 g++ build-essential && \
yarn config set python /usr/bin/python3
# Install sqlite3 dependencies. You can skip this if you don't use sqlite3 in the image,
# in which case you should also move better-sqlite3 to "devDependencies" in package.json.
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
--mount=type=cache,target=/var/lib/apt,sharing=locked \
apt-get update && \
apt-get install -y --no-install-recommends libsqlite3-dev
# From here on we use the least-privileged `node` user to run the backend.
USER node
# This should create the app dir as `node`.
# If it is instead created as `root` then the `tar` command below will fail: `can't create directory 'packages/': Permission denied`.
# If this occurs, then ensure BuildKit is enabled (`DOCKER_BUILDKIT=1`) so the app dir is correctly created as `node`.
WORKDIR /app
# This switches many Node.js dependencies to production mode.
ENV NODE_ENV=production
# Copy repo skeleton first, to avoid unnecessary docker cache invalidation.
# The skeleton contains the package.json of each package in the monorepo,
# and along with yarn.lock and the root package.json, that's enough to run yarn install.
COPY --from=build app/yarn.lock app/package.json app/packages/backend/dist/skeleton.tar.gz ./
RUN tar xzf skeleton.tar.gz && rm skeleton.tar.gz
RUN --mount=type=cache,target=/home/node/.cache/yarn,sharing=locked,uid=1000,gid=1000 \
yarn install --frozen-lockfile --production --network-timeout 300000
# Then copy the rest of the backend bundle, along with any other files we might want.
COPY --from=build app/packages/backend/dist/bundle.tar.gz app/app-config*.yaml ./
RUN tar xzf bundle.tar.gz && rm bundle.tar.gz
CMD ["node", "packages/backend", "--config", "app-config.yaml", "--config", "app-config.production.yaml"]
```
In order to prevent the default `.dockerignore` file from preventing the copying of the relevant files into the first stage of our build, we need to override it with a custom one. This can also be added to the `packages/backend` directory, it should be called `Dockerfile.flightcontrol.dockerignore` and contain the following.
```ssh filename="Dockerfile.flightcontrol.dockerignore"
.git
.yarn/cache
.yarn/install-state.gz
node_modules
packages/*/node_modules
*.local.yaml
```
With these two new files, you will now have the necessary steps in place to build the zip files, copy them into the second stage of the build, and deploy them via Flightcontrol.
# Creating a custom app-config.production file
Our next steps before switching to the Flightcontrol dashboard is to create a custom app-config.production file. The purposes of this is to update how Backstage will connect to the RDS hosted Postgres DB. The default `app-config.production` file uses the `host`, `port`, `user` and `password` environment variables.
When creating a database via the Flightcontrol dashboard, we are given an environment variable with the single connection string. Therefore we need an `app-config.production` file which uses this variable.
Within your Backstage project create a new file called `app-config.production.flightcontrol.yaml`. Add the following configuration to it:
```yaml filename="app-config.production.flightcontrol.yaml"
app:
# Should be the same as backend.baseUrl when using the `app-backend` plugin.
baseUrl: http://localhost:7007
backend:
# Note that the baseUrl should be the URL that the browser and other clients
# should use when communicating with the backend, i.e. it needs to be
# reachable not just from within the backend host, but from all of your
# callers. When its value is "http://localhost:7007", it's strictly private
# and can't be reached by others.
baseUrl: http://localhost:7007
# The listener can also be expressed as a single <host>:<port> string. In this case we bind to
# all interfaces, the most permissive setting. The right value depends on your specific deployment.
listen: ':7007'
# config options: https://node-postgres.com/apis/client
database:
client: pg
pluginDivisionMode: 'schema'
connection:
connectionString: ${POSTGRES_CON_STRING}
ssl:
require: true
rejectUnauthorized: false
# Flightcontrol provides a single DB connection string
# environment variable which can be renamed to POSTGRES_CON_STRING.
# the following default values are therefore not used:
# host: ${POSTGRES_HOST}
# port: ${POSTGRES_PORT}
# user: ${POSTGRES_USER}
# password: ${POSTGRES_PASSWORD}
# https://node-postgres.com/features/ssl
# you can set the sslmode configuration option via the `PGSSLMODE` environment variable
# see https://www.postgresql.org/docs/current/libpq-ssl.html Table 33.1. SSL Mode Descriptions (e.g. require)
# ssl:
# ca: # if you have a CA file and want to verify it you can uncomment this section
# $file: <file-path>/ca/server.crt
catalog:
# Overrides the default list locations from app-config.yaml as these contain example data.
# See https://backstage.io/docs/features/software-catalog/#adding-components-to-the-catalog for more details
# on how to get entities into the catalog.
locations: []
```
Make a note of the environment variable used in the `connectionString`. In our example above this is `POSTGRES_CON_STRING`. You will need this later when you have deployed the database via the Flightcontrol console, and wish to connect to it from Backstage.
# Deployment Via Dashboard
Ensure that custom `Dockerfile.flightcontrol`, `Dockerfile.flightcontrol.dockerignore` and `app-config.production.flightcontrol.yaml` have been committed to your repository before following the next steps.
Login into the Flightcontrol Dashboard and complete each of the following:
1. Create a new project from the Flightcontrol Dashboard
2. Select the GitHub repo for your Backstage project
3. Select `GUI` as the config type:
4. Then, choose `+ Add Web Server (Fargate)` under Services before entering the following server information:
| Field Name | Value |
| ----------------- | ----------------- |
| Build Type | Custom Dockerfile |
| Health Check Path | /catalog |
| Port | 7007 |
5. Click `Create Project` and complete any required steps (like linking your AWS account). Remember to point the project to your custom files.
# Deployment via Code
1. Create a new project from the Flightcontrol Dashboard
2. Select the GitHub repo for your Backstage project
3. Select the `flightcontrol.json` Config Type. Update the example JSON below where applicable to your custom Dockerfile.
```json filename="flightcontrol.json"
{
"$schema": "https://app.flightcontrol.dev/schema.json",
"environments": [
{
"id": "backstage",
"name": "Backstage",
"region": "us-west-2",
"source": {
"branch": "main"
},
"services": [
{
"id": "backstage",
"name": "Backstage",
"type": "fargate",
"buildType": "docker",
"dockerfilePath": "Dockerfile",
"dockerContext": ".",
"healthCheckPath": "/catalog",
"cpu": 0.5,
"memory": 1,
"domain": "backstage.yourapp.com",
"port": 7007,
"minInstances": 1,
"maxInstances": 1
}
]
}
]
}
```
# Databases and Redis
If you need a database or Redis for your Backstage plugins, you can easily add those to your Flightcontrol deployment. For more information, see [the flightcontrol docs](https://www.flightcontrol.dev/docs/guides/flightcontrol/using-code?ref=backstage#redis).
When creating a Postgres RDS database you will need to update the connection string variable name to the one included in the `app-config.production.flightcontrol.yaml`. As noted above in our example we called this `POSTGRES_CON_STRING`.
## Troubleshooting
- [Flightcontrol Documentation](https://www.flightcontrol.dev/docs?ref=backstage)
- [Troubleshooting](https://www.flightcontrol.dev/docs/troubleshooting?ref=backstage)
docs/deployment/heroku.md
-140
View File
@@ -1,140 +0,0 @@
---
id: heroku
title: Deploying with Heroku
sidebar_label: Heroku
description: How to deploy Backstage to 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](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:
```shell
cd your-app/
heroku apps:create <your-app>
```
## Domain
Get Heroku app URL:
```shell
heroku domains -a <your-app>
<your-app-123>.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://<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:
```json
"scripts": {
"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 --config ../../app-config.production.yaml" > Procfile
```
## Database
Provision a [Heroku Postgres](https://elements.heroku.com/addons/heroku-postgresql) database:
```shell
heroku addons:create heroku-postgresql -a <your-app>
```
Update `database` in `app-config.production.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 <your-app>
```
## Deployment
Commit changes and push to Heroku to build and deploy:
```shell
git add Procfile && git commit -am "configure heroku"
git push heroku main
```
View the app in the browser:
```shell
heroku open -a <your-app>
```
View logs:
```shell
heroku logs -a <your-app>
```
## 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 <your-app>
```
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 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:
```shell
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>
```
docs/deployment/index.md
+1 -8
View File
@@ -30,14 +30,7 @@ At Spotify, we deploy software generally by:
This method is covered in [Building a Docker image](docker.md) and
[Deploying with Kubernetes](k8s.md).
There is also an example of deploying on [Heroku](heroku.md), which only
requires the first two steps.
There is also a contrib guide to deploying Backstage with
[AWS Fargate and Aurora PostgreSQL](https://github.com/backstage/backstage/blob/master/contrib/docs/tutorials/aws-fargate-deployment.md).
Please consider contributing other deployment guides if you get Backstage set up
on common infrastructure, it would be a great benefit to the community.
There are many ways to deploy Backstage! You can find more examples in the community contributed guides found [here](https://github.com/backstage/backstage/blob/master/contrib/docs/tutorials/).
If you need to run Backstage behind a corporate proxy, this
[contributed guide](https://github.com/backstage/backstage/blob/master/contrib/docs/tutorials/help-im-behind-a-corporate-proxy.md)
docs/deployment/koyeb.md
-47
View File
@@ -1,47 +0,0 @@
---
id: koyeb
title: Deploying with Koyeb
sidebar_label: Koyeb
description: How to deploy Backstage to Koyeb
---
This guide explains how to deploy Backstage to [Koyeb](https://www.koyeb.com/), a serverless platform that provides the fastest way to deploy applications globally. Koyeb supports git-driven and container-based deployments.
Before you begin, make sure you have a [Koyeb account](https://app.koyeb.com/) to follow this guide.
## Configuring the CLI
First, install the
[Koyeb CLI](https://www.koyeb.com/docs/quickstart/koyeb-cli) and follow the instructions in the [quickstart guide](https://www.koyeb.com/docs/quickstart/koyeb-cli) to login.
Then, configure your `app-config.yaml` with your `baseUrl`:
```yaml
app:
# Should be the same as backend.baseUrl when using the `app-backend` plugin
baseUrl: https://<your-app>.koyeb.app
backend:
baseUrl: https://<your-app>.koyeb.app
listen:
# The $PORT environment variable is a feature of Koyeb
# https://www.koyeb.com/docs/apps/services
port: ${PORT}
```
## Push and deploy Backstage to Koyeb
Push your Backstage application with its [Dockerfile](docker.md) to Koyeb using the following command:
```bash
koyeb app init example-backstage \
--git github.com/<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME> \
--git-branch main \
--ports 8000:http \
--routes /:8000 \
--env PORT=8000
```
Your application will be built and deployed to Koyeb. Once the build has finished, you will be able to access your application running on Koyeb by clicking the URL ending with `.koyeb.app`.
Congratulations! Now you should have Backstage up and running! 🎉