docs: Improve flow for getting-started docs
This commit is contained in:
Tim Hansen
@@ -10,6 +10,9 @@ App.
|
||||
A Backstage App is a monorepo setup with `lerna` that includes everything you
|
||||
need to run Backstage in your own environment.
|
||||
|
||||
If you intend to develop a plugin or contribute to the Backstage project, you
|
||||
may want to [Run Backstage Locally](./running-backstage-locally.md) instead.
|
||||
|
||||
## Create an app
|
||||
|
||||
To create a Backstage app, you will need to have
|
||||
@@ -38,7 +41,96 @@ app-folder is the name that was provided when prompted.
|
||||
Inside that directory, it will generate all the files and folder structure
|
||||
needed for you to run your app.
|
||||
|
||||
### Linking in local Backstage packages
|
||||
### General folder structure
|
||||
|
||||
Below is a simplified layout of the files and folders generated when creating an
|
||||
app.
|
||||
|
||||
```
|
||||
app
|
||||
├── app-config.yaml
|
||||
├── catalog-info.yaml
|
||||
├── lerna.json
|
||||
├── package.json
|
||||
└── packages
|
||||
├── app
|
||||
└── backend
|
||||
```
|
||||
|
||||
- **app-config.yaml**: Main configuration file for the app. See
|
||||
[Configuration](https://backstage.io/docs/conf/) for more information.
|
||||
- **catalog-info.yaml**: Catalog Entities descriptors. See
|
||||
[Descriptor Format of Catalog Entities](https://backstage.io/docs/features/software-catalog/descriptor-format)
|
||||
to get started.
|
||||
- **lerna.json**: Contains information about workspaces and other lerna
|
||||
configuration needed for the monorepo setup.
|
||||
- **package.json**: Root package.json for the project. _Note: Be sure that you
|
||||
don't add any npm dependencies here as they probably should be installed in
|
||||
the intended workspace rather than in the root._
|
||||
- **packages/**: Lerna leaf packages or "workspaces". Everything here is going
|
||||
to be a separate package, managed by lerna.
|
||||
- **packages/app/**: An fully functioning Backstage frontend app, that acts as a
|
||||
good starting point for you to get to know Backstage.
|
||||
- **packages/backend/**: We include a backend that helps power features such as
|
||||
[Authentication](https://backstage.io/docs/auth/),
|
||||
[Software Catalog](https://backstage.io/docs/features/software-catalog/software-catalog-overview),
|
||||
[Software Templates](https://backstage.io/docs/features/software-templates/software-templates-index)
|
||||
and [TechDocs](https://backstage.io/docs/features/techdocs/techdocs-overview)
|
||||
amongst other things.
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
The create app command doesn't always work as expected, this is a collection of
|
||||
some of the commonly encountered issues and solutions.
|
||||
|
||||
#### Couldn't find any versions for "file-saver"
|
||||
|
||||
You may encounter the following error message:
|
||||
|
||||
```text
|
||||
Couldn't find any versions for "file-saver" that matches "eligrey-FileSaver.js-1.3.8.tar.gz-art-external"
|
||||
```
|
||||
|
||||
This is likely because you have a globally configured npm proxy, which breaks
|
||||
the installation of the `material-table` dependency. This is a known issue and
|
||||
being worked on in `material-table`, but for now you can work around it using
|
||||
the following:
|
||||
|
||||
```bash
|
||||
NPM_CONFIG_REGISTRY=https://registry.npmjs.org npx @backstage/create-app
|
||||
```
|
||||
|
||||
#### Can't find Python executable "python"
|
||||
|
||||
The install process may also fail if no Python installation is available. Python
|
||||
is commonly available in most systems already, but if it isn't you can head for
|
||||
example [here](https://www.python.org/downloads/) to install it.
|
||||
|
||||
## Run the app
|
||||
|
||||
When the installation is complete you can open the app folder and start the app.
|
||||
|
||||
```bash
|
||||
cd my-backstage-app
|
||||
yarn start
|
||||
```
|
||||
|
||||
_When `yarn start` is ready it should open up a browser window displaying your
|
||||
app, if not you can navigate to `http://localhost:3000`._
|
||||
|
||||
In most cases you will want to start the backend as well, as it is required for
|
||||
the catalog to work, along with many other plugins.
|
||||
|
||||
To start the backend, open a separate terminal session and run the following in
|
||||
the root directory:
|
||||
|
||||
```bash
|
||||
yarn workspace backend start
|
||||
```
|
||||
|
||||
Now you're free to hack away on your own Backstage installation!
|
||||
|
||||
## Linking in local Backstage packages
|
||||
|
||||
It can often be useful to try out changes to the packages in the main Backstage
|
||||
repo within your own app. For example if you want to make modifications to
|
||||
@@ -89,94 +181,3 @@ invalidate correctly for the linked in packages, causing type checking to not
|
||||
reflect changes made to types. You can work around this by either setting
|
||||
`compilerOptions.incremental = false` in `tsconfig.json`, or by deleting the
|
||||
types cache folder `dist-types` before running `yarn tsc`.
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
The create app command doesn't always work as expected, this is a collection of
|
||||
some of the commonly encountered issues and solutions.
|
||||
|
||||
#### Couldn't find any versions for "file-saver"
|
||||
|
||||
You may encounter the following error message:
|
||||
|
||||
```text
|
||||
Couldn't find any versions for "file-saver" that matches "eligrey-FileSaver.js-1.3.8.tar.gz-art-external"
|
||||
```
|
||||
|
||||
This is likely because you have a globally configured npm proxy, which breaks
|
||||
the installation of the `material-table` dependency. This is a known issue and
|
||||
being worked on in `material-table`, but for now you can work around it using
|
||||
the following:
|
||||
|
||||
```bash
|
||||
NPM_CONFIG_REGISTRY=https://registry.npmjs.org npx @backstage/create-app
|
||||
```
|
||||
|
||||
#### Can't find Python executable "python"
|
||||
|
||||
The install process may also fail if no Python installation is available. Python
|
||||
is commonly available in most systems already, but if it isn't you can head for
|
||||
example [here](https://www.python.org/downloads/) to install it.
|
||||
|
||||
### General folder structure
|
||||
|
||||
Below is a simplified layout of the files and folders generated when creating an
|
||||
app.
|
||||
|
||||
```
|
||||
app
|
||||
├── app-config.yaml
|
||||
├── catalog-info.yaml
|
||||
├── lerna.json
|
||||
├── package.json
|
||||
└── packages
|
||||
├── app
|
||||
└── backend
|
||||
```
|
||||
|
||||
- **app-config.yaml**: Main configuration file for the app. See
|
||||
[Configuration](https://backstage.io/docs/conf/) for more information.
|
||||
- **catalog-info.yaml**: Catalog Entities descriptors. See
|
||||
[Descriptor Format of Catalog Entities](https://backstage.io/docs/features/software-catalog/descriptor-format)
|
||||
to get started.
|
||||
- **lerna.json**: Contains information about workspaces and other lerna
|
||||
configuration needed for the monorepo setup.
|
||||
- **package.json**: Root package.json for the project. _Note: Be sure that you
|
||||
don't add any npm dependencies here as they probably should be installed in
|
||||
the intended workspace rather than in the root._
|
||||
- **packages/**: Lerna leaf packages or "workspaces". Everything here is going
|
||||
to be a separate package, managed by lerna.
|
||||
- **packages/app/**: An fully functioning Backstage frontend app, that acts as a
|
||||
good starting point for you to get to know Backstage.
|
||||
- **packages/backend/**: We include a backend that helps power features such as
|
||||
[Authentication](https://backstage.io/docs/auth/),
|
||||
[Software Catalog](https://backstage.io/docs/features/software-catalog/software-catalog-overview),
|
||||
[Software Templates](https://backstage.io/docs/features/software-templates/software-templates-index)
|
||||
and [TechDocs](https://backstage.io/docs/features/techdocs/techdocs-overview)
|
||||
amongst other things.
|
||||
|
||||
## Run the app
|
||||
|
||||
When the installation is complete you can open the app folder and start the app.
|
||||
|
||||
```bash
|
||||
cd my-backstage-app
|
||||
yarn start
|
||||
```
|
||||
|
||||
_When `yarn start` is ready it should open up a browser window displaying your
|
||||
app, if not you can navigate to `http://localhost:3000`._
|
||||
|
||||
In most cases you will want to start the backend as well, as it is required for
|
||||
the catalog to work, along with many other plugins.
|
||||
|
||||
To start the backend, open a separate terminal session and run the following in
|
||||
the root directory:
|
||||
|
||||
```bash
|
||||
yarn workspace backend start
|
||||
```
|
||||
|
||||
Now you're free to hack away on your own Backstage installation!
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
@@ -4,20 +4,20 @@ title: Getting Started
|
||||
description: Documentation on How to get started with Backstage
|
||||
---
|
||||
|
||||
There are two different ways to get started with Backstage, either by creating a
|
||||
standalone app, or by cloning this repo. Which method you use depends on what
|
||||
you're planning to do.
|
||||
There are two different ways to get started with Backstage:
|
||||
|
||||
Creating a standalone instance makes it simpler to customize the application for
|
||||
your needs whilst staying up to date with the project. You will also depend on
|
||||
`@backstage` packages from npm, making the project much smaller. This is the
|
||||
recommended approach if you want to kick the tyres of Backstage or setup your
|
||||
own instance.
|
||||
- **Recommended:** Create a standalone app
|
||||
- **Contributors:** Clone the Backstage repository
|
||||
|
||||
On the other hand, if you want to contribute plugins or to the project in
|
||||
general, it's easier to fork and clone this project. That will let you stay up
|
||||
to date with the latest changes, and gives you an easier path to make Pull
|
||||
Requests towards this repo.
|
||||
Creating a standalone app makes it simpler to customize the application for your
|
||||
needs and stay up to date with the project. You will depend on `@backstage`
|
||||
packages from npm, making your app much smaller. This is the recommended
|
||||
approach for most installations.
|
||||
|
||||
If you want to contribute plugins or to the project in general, it's easier to
|
||||
fork and clone the repository. The `@backstage` packages will be included in the
|
||||
clone. That will let you stay up to date with the latest changes, and give you
|
||||
an easier path to make Pull Requests.
|
||||
|
||||
### Create your Backstage App
|
||||
|
||||
@@ -37,9 +37,8 @@ subdirectory of your current working directory:
|
||||
npx @backstage/create-app
|
||||
```
|
||||
|
||||
You will be taken through a wizard to create your app, and the output should
|
||||
look something like this. You can read more about this process in
|
||||
[Create an app](https://backstage.io/docs/getting-started/create-an-app).
|
||||
You will be taken through a wizard to create your app. You can read more about
|
||||
this process in [Create an app](./create-an-app).
|
||||
|
||||
### Contributing to Backstage
|
||||
|
||||
|
||||
@@ -4,6 +4,11 @@ title: Running Backstage Locally
|
||||
description: Documentation on How to run Backstage Locally
|
||||
---
|
||||
|
||||
To develop a plugin or contribute to the Backstage project, we recommend cloning
|
||||
the Backstage repository and running locally in development mode. If you not
|
||||
trying to contribute, follow the instructions to
|
||||
[Create an App](./create-an-app.md) instead.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js
|
||||
|
||||
Reference in New Issue
Block a user