Backstage

What is Backstage?

Backstage is an open platform for building developer portals.

Getting started

Install Dependencies

To run the frontend, you will need to have git, NodeJS, and yarn installed.

For running the backend, depending on your OS, you need Docker Desktop for Mac, Docker Desktop for Windows, or for Linux, docker and docker-compose.

The above dependencies are enough to run and work on the Backstage frontend packages. To develop backend services, there are some more tools to install, see backend/README.md. To update protobuf definitions, you will need another set of tools, see proto/README.md.

Secrets

To setup secrets, copy the secrets.env.example to secrets.env as such:

$ make init-secrets

Running Locally

The full local system consists of a collection of backend services, as well as a web application. From the root of the project directory, run the following in a terminal to start up all backend services locally:

cd backend

docker-compose up --build

Once the backend services are up and running, open a separate terminal window and start the web app using the following commands from the project root:

cd frontend

yarn # may take a while

yarn start

The final yarn start command should open a local instance of Backstage in your browser, otherwise open one of the URLs printed in the terminal.

Plugins

Creating a Plugin

Run the following:

$ make scaffold-new-frontend-plugin

This will generate a plugin in the frontend/packages/plugins folder. It is important to note you will still need to include the plugin in your frontend/packages/app in the package.json. You will then be able to import it as follows:

$ make scaffold-new-frontend-plugin
plugin_name [example-plugin]: github-api

$ vim frontend/packages/app/package.json
# Add the following line to your package.json
# Note all plugins are prefixed with "plugin-" by default with a version number of "0.0.0"
# "@backstage/plugin-github-api": "0.0.0",

$ vim frontend/packages/app/src/App.tsx
# Add the following line to import your generated component
# import { ExampleComponent } from '@backstage/plugin-github-api';
# <ExampleComponent />

Protobuf Definitions

The protobuf definitions are all found in the /proto folder in the project root. They are used to generate code for gRPC communication for both the frontend and backend. The generated code is checked into version control though, so unless you want to change the protobuf definitions you don't need to install any tooling.

Information about how to work with the protobuf definitions can be found inside proto/README.md.

Documentation

License

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

3.3 KiB Raw Blame History