coding-to-music
commented
3 years ago Getting Started
https://backstage.io/docs/getting-started/
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
Backstage provides the @backstage/create-app package to scaffold standalone instances of Backstage. You will need to have Node.js Active LTS Release installed (currently v14) and Yarn. You will also need to have Docker installed to use some features like Software Templates and TechDocs.
Using npx you can then run the following to create an app in a chosen subdirectory of your current working directory:
npx @backstage/create-appYou will be taken through a wizard to create your app. You can read more about this process in Create an app.
root@docker-ubuntu-s-1vcpu-2gb-nyc1-01:~/ap# npx @backstage/create-app
npx: installed 70 in 10.633s
? Enter a name for the app [required] my-backstage
? Select database for the backend [required] SQLite
Creating the app...
Checking if the directory is available:
checking my-backstage ✔
Creating a temporary app directory:
creating temporary directory ✔
Preparing files:
copying .dockerignore ✔
copying .eslintrc.js ✔
templating .gitignore.hbs ✔
copying .prettierignore ✔
copying README.md ✔
copying app-config.production.yaml ✔
templating app-config.yaml.hbs ✔
templating catalog-info.yaml.hbs ✔
copying lerna.json ✔
templating package.json.hbs ✔
copying tsconfig.json ✔
copying .eslintrc.js ✔
copying Dockerfile ✔
copying README.md ✔
templating package.json.hbs ✔
copying index.test.ts ✔
copying index.ts ✔
copying types.ts ✔
copying app.ts ✔
copying auth.ts ✔
copying catalog.ts ✔
copying proxy.ts ✔
copying scaffolder.ts ✔
copying search.ts ✔
copying techdocs.ts ✔
copying .eslintrc.js ✔
copying cypress.json ✔
templating package.json.hbs ✔
copying android-chrome-192x192.png ✔
copying apple-touch-icon.png ✔
copying favicon-16x16.png ✔
copying favicon-32x32.png ✔
copying favicon.ico ✔
copying index.html ✔
copying manifest.json ✔
copying robots.txt ✔
copying safari-pinned-tab.svg ✔
copying .eslintrc.json ✔
copying app.js ✔
copying App.test.tsx ✔
copying App.tsx ✔
copying apis.ts ✔
copying index.tsx ✔
copying setupTests.ts ✔
copying LogoFull.tsx ✔
copying LogoIcon.tsx ✔
copying Root.tsx ✔
copying index.ts ✔
copying EntityPage.tsx ✔
copying SearchPage.tsx ✔
Moving to final location:
moving my-backstage ✔
Building the app:
executing yarn install ✔
executing yarn tsc ✔
🥇 Successfully created my-backstage
All set! Now you might want to:
Run the app: cd my-backstage && yarn dev
Set up the software catalog: https://backstage.io/docs/features/software-catalog/configuration
Add authentication: https://backstage.io/docs/auth/
Here are the files created:
root@docker-ubuntu-s-1vcpu-2gb-nyc1-01:~/ap# cd my-backstage/
root@docker-ubuntu-s-1vcpu-2gb-nyc1-01:~/ap/my-backstage# ll
total 936
drwxr-xr-x 3 root root 4096 Aug 28 11:40 dist-types/
drwxr-xr-x 5 root root 4096 Aug 28 11:40 ./
-rw-r--r-- 1 root root 835363 Aug 28 11:39 yarn.lock
drwxr-xr-x 1686 root root 61440 Aug 28 11:39 node_modules/
drwxr-xr-x 52 root root 4096 Aug 28 11:36 ../
drwxr-xr-x 4 root root 4096 Aug 28 11:36 packages/
-rw-r--r-- 1 root root 1595 Aug 28 11:36 package.json
-rw-r--r-- 1 root root 272 Aug 28 11:36 tsconfig.json
-rw-r--r-- 1 root root 116 Aug 28 11:36 lerna.json
-rw-r--r-- 1 root root 353 Aug 28 11:36 catalog-info.yaml
-rw-r--r-- 1 root root 3527 Aug 28 11:36 app-config.yaml
-rw-r--r-- 1 root root 184 Aug 28 11:36 app-config.production.yaml
-rw-r--r-- 1 root root 33 Aug 28 11:36 .prettierignore
-rw-r--r-- 1 root root 150 Aug 28 11:36 README.md
-rw-r--r-- 1 root root 484 Aug 28 11:36 .gitignore
-rw-r--r-- 1 root root 58 Aug 28 11:36 .dockerignore
-rw-r--r-- 1 root root 36 Aug 28 11:36 .eslintrc.js
```java
## Run the app
When the installation is complete you can open the app folder and start the app.
```java
cd my-backstage-app
yarn dev
```java
The yarn dev command will run both the frontend and backend as separate processes (named [0] and [1]) in the same window. When the command finishes running, it should open up a browser window displaying your app. If not, you can open a browser and directly navigate to the frontend at http://localhost:3000.
Now you're free to hack away on your own Backstage installation!
As you get more experienced with the app, in future you can run just the frontend with yarn start in one window, and the backend with yarn start-backend in a different window.
---
id: create-an-app
title: Create an App
description: Documentation on Creating an App
---
To get set up quickly with your own Backstage project you can create a Backstage
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
[Node.js](https://nodejs.org/en/download/) Active LTS Release installed
(currently v14).
Backstage provides a utility for creating new apps. It guides you through the
initial setup of selecting the name of the app and a database for the backend.
The database options are either SQLite or PostgreSQL, where the latter requires
you to set up a separate database instance. If in doubt, choose SQLite, but
don't worry about the choice, it's easy to change later! Here is a
[tutorial](../tutorials/switching-sqlite-postgres.md) for it.
The easiest way to run the create app package is with `npx`:
```bash
npx @backstage/create-appThis will create a new Backstage App inside the current folder. The name of the 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.
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 for more information.
- catalog-info.yaml: Catalog Entities descriptors. See Descriptor Format of Catalog Entities 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, Software Catalog, Software Templates and TechDocs 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:
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:
NPM_CONFIG_REGISTRY=https://registry.npmjs.org npx @backstage/create-appCan'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 to install it.
Could not execute command yarn install
Install yarn on your system with npm install --global yarn or for more details
refer to the
prerequisites
Run the app
When the installation is complete you can open the app folder and start the app.
cd my-backstage-app
yarn devThe yarn dev command will run both the frontend and backend as separate
processes (named [0] and [1]) in the same window. When the command finishes
running, it should open up a browser window displaying your app. If not, you can
open a browser and directly navigate to the frontend at http://localhost:3000.
Now you're free to hack away on your own Backstage installation!
As you get more experienced with the app, in future you can run just the
frontend with yarn start in one window, and the backend with
yarn start-backend in a different window.
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
@backstage/core-plugin-api and try them out in your app.
To link in external packages, add them to your package.json and lerna.json
workspace paths. These can be either relative or absolute paths with or without
globs. For example:
"packages": [
"packages/*",
"plugins/*",
"../backstage/packages/core-plugin-api", // New path added to work on @backstage/core-plugin-api
],Then reinstall packages to make yarn set up symlinks:
yarn installWith this in place you can now modify the @backstage/core-plugin-api package
within the main repo, and have those changes be reflected and tested in your
app. Simply run your app using yarn dev (or yarn start for just frontend) as
normal.
Note that for backend packages you need to make sure that linked packages are
not dependencies of any non-linked package. If you for example want to work on
@backstage/backend-common, you need to also link in other backend plugins and
packages that depend on @backstage/backend-common, or temporarily disable
those plugins in your backend. This is because the transformation of backend
module tree stops whenever a non-local package is encountered, and from that
point node will require packages directly for that entire module subtree.
Type checking can also have issues when linking in external packages, since the
linked in packages will use the types in the external project and dependency
version mismatches between the two projects may cause errors. To fix any of
those errors you need to sync versions of the dependencies in the two projects.
A simple way to do this can be to copy over yarn.lock from the external
project and run yarn install, although this is quite intrusive and can cause
other issues in existing projects, so use this method with care. It can often be
best to simply ignore the type errors, as app serving will work just fine
anyway.
Another issue with type checking is that the incremental type cache doesn't
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.
Backstage
https://github.com/backstage/backstage
https://backstage.io/
https://engineering.atspotify.com/2020/03/17/what-the-heck-is-backstage-anyway/
https://backstage.io/plugins
What is Backstage?
Backstage is an open platform for building developer portals. Powered by a centralized software catalog, Backstage restores order to your microservices and infrastructure and enables your product teams to ship high-quality code quickly — without compromising autonomy.
Backstage unifies all your infrastructure tooling, services, and documentation to create a streamlined development environment from end to end.
Out of the box, Backstage includes:
Backstage was created by Spotify but is now hosted by the Cloud Native Computing Foundation (CNCF) as a Sandbox level project. Read the announcement here.
Project roadmap
A detailed project roadmap, including already delivered milestones, is available here.
Getting Started
Check out the documentation on how to start using Backstage.
Documentation
Community
License
Copyright 2020-2021 © The Backstage Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page: https://www.linuxfoundation.org/trademark-usage
Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0
Security
Please report sensitive security issues via Spotify's bug-bounty program rather than GitHub.
For further details please see our complete security release process.