Merge pull request #27672 from Parsifal-M/docs/getting-started-21828
[DOCS] Restructure the Getting Started Section
This commit is contained in:
Johan Haals
+1
-6
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 \
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
@@ -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.
|
||||
|
||||
@@ -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/)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
+10
-15
@@ -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',
|
||||
{
|
||||
|
||||
+5
-8
@@ -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'
|
||||
|
||||
Reference in New Issue
Block a user