search

backstage / demo

The Backstage demo deployment
Apache License 2.0
112 stars 232 forks source link

readme

Backstage Demo

Link to backstage-demo in Backstage Demo, Component: backstage-demo Entity docs badge, docs: backstage-demo

This repository is the source code for the demo Backstage instance deployed to demo.backstage.io.

Instructions for building your own Backstage instance can be found at the Getting Started portion of the docs.

Reference Project

The sprit of this demo and repository is to showcase Backstage as closely as possible to what you would get from running npx @backstage/create-app@latest to create a new Backstage instance. There have been some additional changes beyond that starting point to help showcase some of Backstage's features more clearly. It also acts as a reference project for how to best keep it up to date and to show a working example of recent architecture patterns like the new backend system.

Core Features

Here are the core features that come with Backstage and links to examples in the demo.

Note: the Kubernetes plugin does need to be installed but is considered a core feature

Additional Plugins

The following plugins have been added to help better illustrate Backstage features and to highlight the ability to add plugins.

Alpha features

The following plugins are considered alpha and still under heavy development. They have been added to the Demo site to showcase them.

Code Customization

We have made some code customization as well. The following sections go into detail about them.

Custom Theme

We have created a custom theme called Aperture to help showcase what some of the possibilities are that a custom theme can allow and to have a working example.

Note: This theme is just an example and not intended to be copied as is.

To view this theme in the Demo:

  1. Go to the Settings area
  2. In the Appearance card for the Theme click on "APERTURE"
  3. The theme will automatically change, now you can explore the Demo to see how this theme looks

The Aperture custom theme code can be found in the aperture.ts file.

More details on creating a custom theme can be found in the Creating a Custom Theme documentation

Home Plugin

Beyond the installation of the Home plugin to get the most out of it you need to setup the initial code for it.

You can find the code in the HomePage.tsx file.

We have also setup the more advanced feature of the Home plugin that allows you to customize it more easily, the code for that in CustomizableHomePage.tsx

To see the more advanced Home in the Demo site you will need to do the following:

  1. Go to the feature flags area
  2. Next click on the toggle labeled "customizable-home-page-preview"
  3. Now refresh the page, feature flags are not reactive by design
  4. Navigate to the Home by clicking on the "Home" icon in the sidebar
  5. You should now see the more advanced Home, clicking on the "EDIT" button is a good place to start playing around with the features

More details on the Home plugin can be found in the Backstage homepage - Setup and Customization documentation.

Search

The Search plugin has been expanded to include results from the Explore plugins Tools list. This has been done in two places:

  1. Frontend changes are in the SearchPage.tsx file
  2. Backend changes are here the index.ts file

Note: currently Search is setup on the frontend to include results from TechDocs but it is disabled in the backend due to a bug that happens with an unusual setup like the Demo site.

More information on adjusting search can be found in the Customizing Search documentation.

Upgrading

This Demo site is kept in-sync with the weekly next release line as defined in the Release Lines documentation. Upgrading the Demo site has been automated so that a Pull Request with the latest changes is created the day after the weekly next release is published. This allows us to easily stay up to date!

The automation is done using a GitHub workflow but the concepts and most of its parts could easily be transferred to other CI/CD systems like Azure DevOps Pipelines, CircleCI, etc. The parts of this workflow can be found here:

Dependency Updates

As Backstage uses packages for its various dependencies these will need to be kept up to date. We use Renovate as it is incredibly helpful in keeping dependency versions up to date. Renovate will create Pull Requests for the various dependencies and all we need to to is review and merge them!

You can see our Renovate configuration in the renovate.json file and example Pull Requests here

Note: you may not see any Pull Request as we very much like to stay on top of them, clicking on the "Closed" option will let you see examples that have been merged in the past.

To learn how to get started with Renovate we recommend reading the Installing and onboarding Renovate into repositories documentation.

Working With This Repo

The following sections are to help those working with this repo to keep in maintained.

Local Docker

The Dockerfile in this repo can be built locally using the following command:

docker image build .  -t demo --build-arg ENVIRONMENT_CONFIG=local

This will build the image with your app-config.local.yaml included this allows you to include any config you might want to have in place for local testing.

Using --progress=plain --no-cache can also be helpful with testing changes.

You can then run it with this command:

docker run -it -p 7007:7007 demo