diff --git a/docs/deployment/flightcontrol.md b/contrib/docs/tutorials/flightcontrol-deployment.md similarity index 98% rename from docs/deployment/flightcontrol.md rename to contrib/docs/tutorials/flightcontrol-deployment.md index df0c9284fb..aee915ba2f 100644 --- a/docs/deployment/flightcontrol.md +++ b/contrib/docs/tutorials/flightcontrol-deployment.md @@ -1,9 +1,4 @@ ---- -id: flightcontrol -title: Deploying with Flightcontrol -sidebar_label: AWS Fargate via Flightcontrol -description: Deploying Backstage to AWS Fargate via Flightcontrol ---- +# Deploying Backstage to AWS with 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. diff --git a/docs/deployment/heroku.md b/contrib/docs/tutorials/heroku-deployment.md similarity index 96% rename from docs/deployment/heroku.md rename to contrib/docs/tutorials/heroku-deployment.md index 8961848894..2dea1f021c 100644 --- a/docs/deployment/heroku.md +++ b/contrib/docs/tutorials/heroku-deployment.md @@ -1,9 +1,4 @@ ---- -id: heroku -title: Deploying with Heroku -sidebar_label: Heroku -description: How to deploy Backstage to Heroku ---- +# Deploying Backstage to Heroku Heroku is a Platform as a Service (PaaS) designed to simplify application deployment. diff --git a/docs/deployment/koyeb.md b/contrib/docs/tutorials/koyeb-deployment.md similarity index 86% rename from docs/deployment/koyeb.md rename to contrib/docs/tutorials/koyeb-deployment.md index 3e30881752..75d42d8814 100644 --- a/docs/deployment/koyeb.md +++ b/contrib/docs/tutorials/koyeb-deployment.md @@ -1,9 +1,4 @@ ---- -id: koyeb -title: Deploying with Koyeb -sidebar_label: Koyeb -description: How to deploy Backstage to Koyeb ---- +# Deploying 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. @@ -31,7 +26,7 @@ backend: ## Push and deploy Backstage to Koyeb -Push your Backstage application with its [Dockerfile](docker.md) to Koyeb using the following command: +Push your Backstage application with its [Dockerfile](https://backstage.io/docs/deployment/docker) to Koyeb using the following command: ```bash koyeb app init example-backstage \ diff --git a/docs/deployment/backstage-deploy/aws.md b/docs/deployment/backstage-deploy/aws.md deleted file mode 100644 index 818850a6f5..0000000000 --- a/docs/deployment/backstage-deploy/aws.md +++ /dev/null @@ -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="" -``` - -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. diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md index 79be3cb074..3d2abf00b8 100644 --- a/docs/deployment/docker.md +++ b/docs/deployment/docker.md @@ -5,6 +5,10 @@ sidebar_label: Docker description: How to build a Backstage Docker image for deployment --- +:::note Note +Before you start this section, it would be good to have a basic understanding of Docker and how it works. If you are new to Docker, you can start with the [Docker overview](https://docs.docker.com/get-started/overview/) guide. +::: + This section describes how to build a Backstage App into a deployable Docker image. It is split into three sections, first covering the host build approach, which is recommended due to its speed and more efficient and often simpler diff --git a/docs/deployment/index.md b/docs/deployment/index.md index 0524e71db8..76c8c12932 100644 --- a/docs/deployment/index.md +++ b/docs/deployment/index.md @@ -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) diff --git a/docs/getting-started/concepts.md b/docs/getting-started/concepts.md deleted file mode 100644 index f8aba8537d..0000000000 --- a/docs/getting-started/concepts.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -id: concepts -title: Key Concepts -# prettier-ignore -description: High level key concepts used in the Backstage project ---- - -For users of Backstage, there are certain concepts which are central to its -design and functionality. Being an expert in each of these concepts is not -necessary, however having a base understanding of each will make administering, -configuring, and operating Backstage easier. - -- CHANGELOG - https://keepachangelog.com -- Docker - https://www.docker.com/ -- Monorepo - https://semaphoreci.com/blog/what-is-monorepo -- Node.js - https://nodejs.org -- React - https://reactjs.org -- Semantic Versioning - https://semver.org -- TypeScript - https://www.typescriptlang.org -- YAML - https://yaml.org -- Yarn - https://www.pluralsight.com/guides/yarn-a-package-manager-for-node-js diff --git a/docs/getting-started/configure-app-with-plugins.md b/docs/getting-started/configure-app-with-plugins.md index 95fd456dc0..c31cdc0a06 100644 --- a/docs/getting-started/configure-app-with-plugins.md +++ b/docs/getting-started/configure-app-with-plugins.md @@ -4,6 +4,14 @@ title: Configuring App with plugins description: Documentation on How Configuring App with plugins --- +Audience: Developers + +:::note Note +Backstage plugins are primarily written using [TypeScript](https://www.typescriptlang.org), [Node.js](https://nodejs.org) and [React](https://reactjs.org). Having an understanding of these technologies will be beneficial on your journey to customizing Backstage! +::: + +## Summary + Backstage plugins customize the app for your needs. There is a [plugin directory](https://backstage.io/plugins) with plugins for many common infrastructure needs - CI/CD, monitoring, auditing, and more. diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 926225724a..687cf0be16 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -7,6 +7,10 @@ description: How to install Backstage for your own use. Audience: Developers and Admins +:::note Note +It is not required, although recommended to have a basic understanding of [Yarn](https://www.pluralsight.com/guides/yarn-a-package-manager-for-node-js) and [npm](https://docs.npmjs.com/about-npm) before starting this guide. +::: + ## Summary This guide walks through how to get started creating your very own Backstage customizable app. This is the first step in evaluating, developing on, or demoing Backstage. @@ -21,7 +25,7 @@ If you are planning to contribute a new feature or bug fix to the Backstage proj ## Prerequisites -This guide assumes a basic understanding of working on a Linux based operating system and have some experience with the terminal, specifically, these commands: `npm`, `yarn`. +This guide also assumes a basic understanding of working on a Linux based operating system and have some experience with the terminal, specifically, these commands: `npm`, `yarn`. - Access to a Unix-based operating system, such as Linux, macOS or [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/) diff --git a/docs/getting-started/keeping-backstage-updated.md b/docs/getting-started/keeping-backstage-updated.md index 08b89db518..01e6c6ddeb 100644 --- a/docs/getting-started/keeping-backstage-updated.md +++ b/docs/getting-started/keeping-backstage-updated.md @@ -4,6 +4,14 @@ title: Keeping Backstage Updated description: How to keep your Backstage App updated --- +Audience: Developers and Admins + +:::note Note +To better understand the concepts in this section, it's recommended to have an understanding of [Monorepos](https://semaphoreci.com/blog/what-is-monorepo), [Semantic Versioning](https://semver.org) and [CHANGELOGs](https://keepachangelog.com). +::: + +## Summary + Backstage is always improving, so it's a good idea to stay in sync with the latest releases. Backstage is more of a library than an application or service; similar to `create-react-app`, the `@backstage/create-app` tool gives you a diff --git a/docs/getting-started/register-a-component.md b/docs/getting-started/register-a-component.md index c935d25807..4e2076ee8d 100644 --- a/docs/getting-started/register-a-component.md +++ b/docs/getting-started/register-a-component.md @@ -6,6 +6,10 @@ description: Start populating your Backstage app with your data. Audience: Developers +:::note Note +Entity files are stored in YAML format, if you are not familiar with YAML, you can learn more about it [here](https://yaml.org). +::: + ## Summary This guide will walk you through how to pull Backstage data from other locations manually. There are integrations that will automatically do this for you. diff --git a/microsite/sidebars.js b/microsite/sidebars.js index 871cec0a0f..954b3630b1 100644 --- a/microsite/sidebars.js +++ b/microsite/sidebars.js @@ -27,6 +27,16 @@ module.exports = { 'getting-started/homepage', ], }, + { + type: 'category', + label: 'Deploying Backstage', + items: [ + 'deployment/index', + 'deployment/scaling', + 'deployment/docker', + 'deployment/k8s', + ], + }, { type: 'category', label: 'Using Backstage', @@ -37,7 +47,6 @@ module.exports = { ], }, 'getting-started/keeping-backstage-updated', - 'getting-started/concepts', ], 'Core Features': [ { @@ -341,20 +350,6 @@ module.exports = { }, 'tooling/package-metadata', ], - Deployment: [ - 'deployment/index', - 'deployment/scaling', - 'deployment/docker', - 'deployment/k8s', - 'deployment/heroku', - 'deployment/koyeb', - 'deployment/flightcontrol', - { - type: 'category', - label: 'Using Backstage Deploy (alpha)', - items: ['deployment/backstage-deploy/aws-lightsail'], - }, - ], 'New Backend System': [ 'backend-system/index', { diff --git a/mkdocs.yml b/mkdocs.yml index 76467e9476..38b12b9ead 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,12 +30,16 @@ nav: - Configuring App with plugins: 'getting-started/configure-app-with-plugins.md' - Customize the look-and-feel of your App: 'getting-started/app-custom-theme.md' - Customizing your Homepage: 'getting-started/homepage.md' + - Deployment: + - Deploying Backstage: 'deployment/index.md' + - Scaling: 'deployment/scaling.md' + - Docker: 'deployment/docker.md' + - Kubernetes: 'deployment/k8s.md' - Using Backstage: - Logging in: 'getting-started/logging-in.md' - Register a component: 'getting-started/register-a-component.md' - Create a component: 'getting-started/create-a-component.md' - Keeping Backstage Updated: 'getting-started/keeping-backstage-updated.md' - - Key Concepts: 'getting-started/concepts.md' - Core Features: - Software Catalog: - Overview: 'features/software-catalog/index.md' @@ -189,13 +193,6 @@ nav: - Debugging Backstage: 'tooling/local-dev/debugging.md' - Profiling Backstage: 'tooling/local-dev/profiling.md' - Package Metadata: 'tooling/package-metadata.md' - - Deployment: - - Deploying Backstage: 'deployment/index.md' - - Scaling: 'deployment/scaling.md' - - Docker: 'deployment/docker.md' - - Kubernetes: 'deployment/k8s.md' - - Heroku: 'deployment/heroku.md' - - Koyeb: 'deployment/koyeb.md' - Designing for Backstage: - Design: 'dls/design.md' - Component Design Guidelines: 'dls/component-design-guidelines.md'