This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Backstage

Here you will find information about Backstage, it’s plugins and usage tutorials

1 - Backstage Description

Backstage by Spotify can be seen as a Platform Portal. It is an open platform for building and managing internal developer tools, providing a unified interface for accessing various tools and resources within an organization.

Key Features of Backstage as a Platform Portal: Tool Integration:

Backstage allows for the integration of various tools used in the development process, such as CI/CD, version control systems, monitoring, and others, into a single interface. Service Management:

It offers the ability to register and manage services and microservices, as well as monitor their status and performance. Documentation and Learning Materials:

Backstage includes capabilities for storing and organizing documentation, making it easier for developers to access information. Golden Paths:

Backstage supports the concept of “Golden Paths,” enabling teams to follow recommended practices for development and tool usage. Modularity and Extensibility:

The platform allows for the creation of plugins, enabling users to customize and extend Backstage’s functionality to fit their organization’s needs. Backstage provides developers with centralized and convenient access to essential tools and resources, making it an effective solution for supporting Platform Engineering and developing an internal platform portal.

2 - Backstage Local Setup Tutorial

This document provides a comprehensive guide on the prerequisites and the process to set up and run Backstage locally on your machine.

Table of Contents

  1. Prerequisites
  2. Setting Up Backstage
  3. Run the Backstage Application

Prerequisites

Before you start, make sure you have the following installed on your machine:

  1. Node.js: Backstage requires Node.js. You can download it from the Node.js website. It is recommended to use the LTS version.

  2. Yarn: Backstage uses Yarn as its package manager. You can install it globally using npm:

    npm install --global yarn

  3. Git

  4. Docker

Setting Up Backstage

To install the Backstage Standalone app, you can use npx. npx is a tool that comes preinstalled with Node.js and lets you run commands straight from npm or other registries.

npx @backstage/create-app@latest

This command will create a new directory with a Backstage app inside. The wizard will ask you for the name of the app. This name will be created as sub directory in your current working directory.

Below is a simplified layout of the files and folders generated when creating an app.

app
├── app-config.yaml
├── catalog-info.yaml
├── 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.
  • 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/: A 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.

Run the Backstage Application

You can run it in Backstage root directory by executing this command:

yarn dev

3 - Existing Backstage Plugins

  1. Catalog:

    • Used for managing services and microservices, including registration, visualization, and the ability to track dependencies and relationships between services. It serves as a central directory for all services in an organization.

  2. Docs:

    • Designed for creating and managing documentation, supporting formats such as Markdown. It helps teams organize and access technical and non-technical documentation in a unified interface.

  3. API Docs:

    • Automatically generates API documentation based on OpenAPI specifications or other API definitions, ensuring that your API information is always up to date and accessible for developers.

  4. TechDocs:

    • A tool for creating and publishing technical documentation. It is integrated directly into Backstage, allowing developers to host and maintain documentation alongside their projects.

  5. Scaffolder:

    • Allows the rapid creation of new projects based on predefined templates, making it easier to deploy services or infrastructure with consistent best practices.

  6. CI/CD:

    • Provides integration with CI/CD systems such as GitHub Actions and Jenkins, allowing developers to view build status, logs, and pipelines directly in Backstage.

  7. Metrics:

    • Offers the ability to monitor and visualize performance metrics for applications, helping teams to keep track of key indicators like response times and error rates.

  8. Snyk:

    • Used for dependency security analysis, scanning your codebase for vulnerabilities and helping to manage any potential security risks in third-party libraries.

  9. SonarQube:

    • Integrates with SonarQube to analyze code quality, providing insights into code health, including issues like technical debt, bugs, and security vulnerabilities.

  10. GitHub:

  • Enables integration with GitHub repositories, displaying information such as commits, pull requests, and other repository activity, making collaboration more transparent and efficient.
  1. CircleCI:
  • Allows seamless integration with CircleCI for managing CI/CD workflows, giving developers insight into build pipelines, test results, and deployment statuses.
  1. Kubernetes:
  • Provides tools to manage Kubernetes clusters, including visualizing pod status, logs, and cluster health, helping teams maintain and troubleshoot their cloud-native applications.
  1. Cloud:
  • Includes plugins for integration with cloud providers like AWS and Azure, allowing teams to manage cloud infrastructure, services, and billing directly from Backstage.
  1. OpenTelemetry:
  • Helps with monitoring distributed applications by integrating OpenTelemetry, offering powerful tools to trace requests, detect performance bottlenecks, and ensure application health.
  1. Lighthouse:
  • Integrates Google Lighthouse to analyze web application performance, helping teams identify areas for improvement in metrics like load times, accessibility, and SEO.

4 - Plugin Creation Tutorial

Backstage plugins and functionality extensions should be writen in TypeScript/Node.js because backstage is written in those languages

General Algorithm for Adding a Plugin in Backstage

  1. Create the Plugin
    To create a plugin in the project structure, you need to run the following command at the root of Backstage:

    yarn new --select plugin

    The wizard will ask you for the plugin ID, which will be its name. After that, a template for the plugin will be automatically created in the directory plugins/{plugin id}. After this install all needed dependencies. After this install required dependencies. In example case this is "axios" for API requests
    Emaple:

     yarn add axios

  2. Define the Plugin’s Functionality
    In the newly created plugin directory, focus on defining the plugin’s core functionality. This is where you will create components that handle the logic and user interface (UI) of the plugin. Place these components in the plugins/{plugin_id}/src/components/ folder, and if your plugin interacts with external data or APIs, manage those interactions within these components.

  3. Set Up Routes
    In the main configuration file of your plugin (typically plugins/{plugin_id}/src/routs.ts), set up the routes. Use createRouteRef() to define route references, and link them to the appropriate components in your plugins/{plugin_id}/src/components/ folder. Each route will determine which component renders for specific parts of the plugin.

  4. Register the Plugin
    Navigate to the packages/app folder and import your plugin into the main application. Register your plugin in the routs array within packages/app/src/App.tsx to integrate it into the Backstage system. It will create a rout for your’s plugin page

  5. Add Plugin to the Sidebar Menu
    To make the plugin accessible through the Backstage sidebar, modify the sidebar component in packages/app/src/components/Root.tsx. Add a new sidebar item linked to your plugin’s route reference, allowing users to easily access the plugin through the menu.

  6. Test the Plugin
    Run the Backstage development server using yarn dev and navigate to your plugin’s route via the sidebar or directly through its URL. Ensure that the plugin’s functionality works as expected.

Example

All steps will be demonstrated using a simple example plugin, which will request JSON files from the API of jsonplaceholder.typicode.com and display them on a page.

  1. Creating test-plugin:

    yarn new --select plugin

    Adding required dependencies. In this case only “axios” is needed for API requests

    yarn add axios

  2. Implement code of the plugin component in plugins/{plugin-id}/src/{Component name}/{filename}.tsx

    import React, { useState } from 'react';
import axios from 'axios';
import { Typography, Grid } from '@material-ui/core';
import {
  InfoCard,
  Header,
  Page,
  Content,
  ContentHeader,
  SupportButton,
} from '@backstage/core-components';

export const TestComponent = () => {
  const [posts, setPosts] = useState<any[]>([]);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const fetchPosts = async () => {
    setLoading(true);
    setError(null);

    try {
      const response = await axios.get('https://jsonplaceholder.typicode.com/posts');
      setPosts(response.data);
    } catch (err) {
      setError('Ошибка при получении постов');
    } finally {
      setLoading(false);
    }
  };

  return (
    <Page themeId="tool">
      <Header title="Welcome to the Test Plugin!" subtitle="This is a subtitle">
        <SupportButton>A description of your plugin goes here.</SupportButton>
      </Header>
      <Content>
        <ContentHeader title="Posts Section">
          <SupportButton>
            Click to load posts from the API.
          </SupportButton>
        </ContentHeader>
        <Grid container spacing={3} direction="column">
          <Grid item>
            <InfoCard title="Information Card">
              <Typography variant="body1">
                This card contains information about the posts fetched from the API.
              </Typography>
              {loading && <Typography>Загрузка...</Typography>}
              {error && <Typography color="error">{error}</Typography>}
              {!loading && !posts.length && (
                <button onClick={fetchPosts}>Request Posts</button>
              )}
            </InfoCard>
          </Grid>
          <Grid item>
            {posts.length > 0 && (
              <InfoCard title="Fetched Posts">
                <ul>
                  {posts.map(post => (
                    <li key={post.id}>
                    <Typography variant="h6">{post.title}</Typography>
                    <Typography>{post.body}</Typography>
                    </li>
                   ))}
                </ul>
              </InfoCard>
            )}
          </Grid>
        </Grid>
      </Content>
    </Page>
  );
};

  3. Setup routs in plugins/{plugin_id}/src/routs.ts

import { createRouteRef } from '@backstage/core-plugin-api';

export const rootRouteRef = createRouteRef({
  id: 'test-plugin',
});
  1. Register the plugin in packages/app/src/App.tsx in routes Import of the plugin:
import { TestPluginPage } from '@internal/backstage-plugin-test-plugin';

Adding route:

const routes = (
    <FlatRoutes>
       ... //{Other Routs}
       <Route path="/test-plugin" element={<TestPluginPage />} />
    </FlatRoutes>
)
  1. Add Item to sidebar menu of the backstage in packages/app/src/components/Root/Root.tsx. This should be added in to Root object as another SidebarItem
export const Root = ({ children }: PropsWithChildren<{}>) => (
  <SidebarPage>
    <Sidebar>
      ... //{Other sidebar items}
      <SidebarItem icon={ExtensionIcon} to="/test-plugin" text="Test Plugin" />
    </Sidebar>
    {children}
  </SidebarPage>
);
  1. Plugin is ready. Run the application
 yarn dev

example example