From cdd6d1db7c47da24abcfd257f0796b1137a69b44 Mon Sep 17 00:00:00 2001 From: Tim Hansen Date: Mon, 1 Mar 2021 14:33:29 -0700 Subject: [PATCH 1/2] docs: Improve flow for getting-started docs --- docs/getting-started/create-an-app.md | 185 +++++++++--------- docs/getting-started/index.md | 29 ++- .../running-backstage-locally.md | 5 + microsite/sidebars.json | 6 +- 4 files changed, 115 insertions(+), 110 deletions(-) diff --git a/docs/getting-started/create-an-app.md b/docs/getting-started/create-an-app.md index 9abb68d21b..adc74b78d6 100644 --- a/docs/getting-started/create-an-app.md +++ b/docs/getting-started/create-an-app.md @@ -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 diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index b946039dfb..f36efe5d6f 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -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 diff --git a/docs/getting-started/running-backstage-locally.md b/docs/getting-started/running-backstage-locally.md index fe68937c4e..01ee6bca3f 100644 --- a/docs/getting-started/running-backstage-locally.md +++ b/docs/getting-started/running-backstage-locally.md @@ -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 diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 8b5c0e5f0c..793da7bcf1 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -12,9 +12,8 @@ ], "Getting Started": [ "getting-started/index", - "getting-started/running-backstage-locally", - "getting-started/contributors", "getting-started/create-an-app", + "getting-started/running-backstage-locally", { "type": "subcategory", "label": "App configuration", @@ -32,7 +31,8 @@ "getting-started/deployment-helm", "getting-started/deployment-other" ] - } + }, + "getting-started/contributors" ], "CLI": ["cli/index", "cli/commands"], "Core Features": [ From 64615dd726f3334fef1d7c690ef877339387ed4d Mon Sep 17 00:00:00 2001 From: Tim Hansen Date: Mon, 1 Mar 2021 14:48:02 -0700 Subject: [PATCH 2/2] Fix relative link --- docs/getting-started/index.md | 2 +- docs/getting-started/running-backstage-locally.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index f36efe5d6f..2536944a7c 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -38,7 +38,7 @@ npx @backstage/create-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). +this process in [Create an app](./create-an-app.md). ### Contributing to Backstage diff --git a/docs/getting-started/running-backstage-locally.md b/docs/getting-started/running-backstage-locally.md index 01ee6bca3f..873c26a099 100644 --- a/docs/getting-started/running-backstage-locally.md +++ b/docs/getting-started/running-backstage-locally.md @@ -5,7 +5,7 @@ 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 +the Backstage repository and running locally in development mode. If you are not trying to contribute, follow the instructions to [Create an App](./create-an-app.md) instead.