How to easily create standardised software templates with Backstage

11.05.2022Stefan Welsch
Cloud Backstage TypeScript Node.js

backstage

Backstage describes itself as an open platform to build developer portals. The software was developed by Spotify 2020 under the Open Source Projects and is written in Typescript. Spotify itself uses the software for internal software development.

Today we want to take a closer look at Backstage and will try to design our own template.

Out-of-the-box, Backstage offers a Software Catalog with which we can manage all our software. This includes, for example, microservices, libraries, websites, data pipelines, etc. We can create new entities in the software catalogue based on Software Templates, or register existing software. This is important so that you can import existing software into Backstage.

Software Templates provide us with a standardised way to create software. Best practices and toolsets can be stored in the template, which can be used by all developers. Automation of build and deployment processes can also be built directly into the software templates.

Backstage also offers us TechDocs. Here, technical documentation can be easily created and maintained. This way you have the technical documentation centrally in one place and always close to the software it belongs to.

To understand what exactly Backstage does, the easiest way is to start a local server. Backstage offers a CLI for this purpose, with which we can create an app. An app contains a backend and frontend, which we can configure according to our wishes.

Get started

Before we can run Backstage locally, certain preconditions must be fulfilled. Once we have installed all the programs, we can create an app with the following command. As name I choose dev-manager and as database we use SQLite for local development.

1
2
3
4
5
~ ❯ npx @backstage/create-app
? Enter a name for the app [required] dev-manager
? Select database for the backend [required] (Use arrow keys)
❯ SQLite
PostgreSQL

Our app will now be created. After the creation is done, we can start it with the following command.

1
2
cd dev-manager
yarn dev

A browser window should now open with the application.

backstage-dashboard

Let’s have a look at the application in detail. On the start page we find an overview of all our components. A component can be of type library, website or service. Based on the components, the specific view will be built later.

Under APIs we find an API catalogue. In this, as the name says, all APIs can be found. Here, too, there are different types (grpc, openapi, graphql and asyncapi), which influence the detailed view.

image-20220324110217575

In the Docs view we find technical documentation for our components. This way, the documentation, the API as well as the implementation are in one central place.

image-20220324110241814

Under the menu item Create… we find various templates with which we can create a new component, API or documentation.

image-20220324110405321

The TechRadar menu item provides an overview of the most used or newest technologies. This is very useful if you want to make sure that you use the latest technologies for new projects.

image-20220401073248268

As we can see, Backstage out-of-the-box already provides a good overview of the software components used.

Templates

As already mentioned in the intro, we want to take a look at the templates. Templates, as the name suggests, are templates for software projects. But what do you need these templates for anyway?

In the age of microservices, the quantity of software projects has increased dramatically. In the past, we still had “eggshell applications” that had to offer as many functionalities as possible. All components of the software were developed in this one application. For example, a user was authenticated, then a service was called which retrieved certain user roles from LDAP for authentication. Then a service was called again, which read out information about this user from a database, etc.

Today, this one application is built in a microservice architecture, so there is one service to authenticate the user, another to read the roles from the LDAP and another to do the database access. This is only a highly simplified example. In reality, there are often dozens of microservices, which are then also managed by different teams within an organisation, or even several organisations.

To ensure the maintenance of these applications, it makes sense that each team adheres to certain guidelines and rules when creating and developing these applications. This is exactly where templates help us. We can specify naming, folder structures, tools and best practices in templates. Let’s take a look at a template using a Quarkus application. To do this, we use the Quarkus Configurator to create a new application with the desired tools.

image-20220401080946386

So we want to use gRPC services in our application, the configuration should always be in YAML. So that we have a uniform logging output, we use the logging JSON. As a programming language we use Kotlin instead of Java by default and last but not least we want to use Gradle as a build tool.

Via the button “Generate your application” we can now download a .zip with the source code and unpack the project. To create a backstage template, we create a folder called quarkus-template and within this folder we create a folder called template.

1
mkdir -p quarkus-template/template

Now we move the whole content of our Quarkus project into the template folder. The folder structure should look like this.

image-20220401084438228

Now let’s get to work and create a template from our application. First we create a file called template.yaml in the root. This file defines the meta data of our template like name, description, parameters and which actions should be executed. The content of this file looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: quarkus-template # name of the template
  title: Quarkus Application 
  description: Create a quarkus application
  tags: # you can configure tags for the service
    - recommended
    - quarkus
    - microservice
    - kotlin
    
spec:
  owner: stefan.welsch@b-nova.com # the owner of this 
  type: service # backstage type of this template
  
  # these are the steps which are rendered in the frontend with the form input
  parameters:
    - title: Provide some simple information
      required:
        - name
        - package
      properties:
        name:
          title: Name
          type: string
          description: Unique name of the component
          ui:field: EntityNamePicker
        package:
          title: Package
          type: string
          description: Package name
    - title: Choose a location
      required:
        - repoUrl
      properties:
        repoUrl:
          title: Repository Location
          type: string
          ui:field: RepoUrlPicker
          ui:options:
            allowedHosts:
              - github.com    
	# here are the steps that are executed in series in the scaffolder backend
  steps:
    - id: template
      name: Fetch Skeleton + Template
      action: fetch:template
      input:
        url: ./template
        values:
          name: ${{ parameters.name }}
          package: ${{ parameters.package }}
          
    - id: publish
      name: Publish
      action: publish:github
      input:
        allowedHosts: ["github.com"]
        description: This is ${{ parameters.name }}
        repoUrl: ${{ parameters.repoUrl }}
        defaultBranch: main

    - id: register
      name: Register
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
        catalogInfoPath: "/catalog-info.yaml"

  output:
    remoteUrl: ${{ steps.publish.output.remoteUrl }}
    entityRef: ${{ steps.register.output.entityRef }}

Now we first want to make the name of our application configurable. To do this, we search for code-with-quarkus (current name) in our project and replace it with the placeholder {{values.name}}. Then we want to make the package name configurable. Currently this is org.acme. So we search the whole project for org.acme and replace it with ${{values.package}}. Now we just have to change the package name in the folder src/main/kotlinto${{values.package}}`.

image-20220401085340354

Our template is now ready. Now we want to make the template available in the backstage. To do this, we first have to convert the template into a Git directory. To do this, we change to our dev-manager project and open the file app-config.yaml. Under the item catalog we find various locations. These are the sample data that we have seen above. First we delete all templates from the locations and add our own.

image-20220401091539749

INFO

If you see the following error in the log

1
[1] 2022-04-01T07:12:53.576Z catalog warn Entity template:default/quarkus-template at file:/Users/swelsch/quarkus-template/template.yaml, originated at file:/Users/swelsch/quarkus-template/template. yaml, is not of an allowed kind for that location type=plugin entity=location:default/generated-6fcbb905406738fb7c50408b044fc21e09da61c7

you still have to add template to the Catalog Rules.

image-20220401091802313

If we now start the Backstage application, we should now see our own template under the menu item “Create”.

image-20220401092056039

Before we can create our first own application, we need a repository where we will publish our code later. In our example we use Github. To do this, we first need to create a developer token in Github. We can create such a token at https://github.com/settings/tokens/new (an account is required). The following permissions are required.

image-20220401093527176

We can then add the Github token to the app-config.yaml under the Github integration. The token should not be inserted in plain text. Please use your appropriate secrets management mechanism to read the token from the environment variables at runtime.

Screenshot 2022-04-01 at 09.37.58

After our Github connection is configured, we now want to create our first own application from our template. To do this, we click on “Choose “ and enter the name and package of the project in the following dialogue.

image-20220401092330030

In the next step we have to specify in which repository the project should be stored. As owner we simply enter our Github username, and as repository the name.

image-20220401094657956

With a click on “Next Step “ we see another summary. If everything is ok, we can click on “Create” to create the project.

image-20220401094858922

Now we see that the steps “Fetch Skeleton + Template “ and “Publish “ have been successfully executed. However, there is still an error in the “Register “ step, which we will deal with later.

image-20220401100214430

Now let’s check how the project was created in Github and if the variable substitution worked.

image-20220401100532871

The project was correctly created as a test and everything in the readme was also correctly replaced. So we have successfully created our first own template and made our first application from it. :-)

Catalogue registration

Now let’s take a look at why the component was not registered in the Backstage Software catalogue.

image-20220401100214430

As we can see from the error message, a file called catalog-info.yaml is missing. This is necessary to register new, but also existing components in the software catalogue. So we have to add this file to our template. The content of the file is quite simple. We only have to specify a few metadata.

1
2
3
4
5
6
7
8
9
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: ${{values.name | dump}}
  description: ${{values.description | dump}}
spec:
  type: service
  lifecycle: experimental
  owner: ${{values.owner | dump}}

If we now want to add our already created project to the software catalogue, it is sufficient to simply add this file to the repository.

We can do this directly in Github via “Add File “.

image-20220401101404107

Now we can add the component directly in the backstage. To do this, we go to the menu item “Create “ and click “Register Existing Component “. As path we simply enter the complete path to catalog-info.

image-20220401101616138

By clicking on “Analyze “ the catalog-info should now be found and you can import it by clicking on the button “Import”. Under “Home” we should now see this new component.

image-20220401101755336

Conclusion

You have now got to know Backstage and seen how you can easily and very elegantly make software templates available in your company. Backstage is a good start so that developers can concentrate on their core competence again, namely programming.

Stefan Welsch

Stefan Welsch – Pionier, Stuntman, Mentor. Als Gründer von b-nova ist Stefan immer auf der Suche nach neuen und vielversprechenden Entwicklungsfeldern. Er ist durch und durch Pragmatiker und schreibt daher auch am liebsten Beiträge die sich möglichst nahe an 'real-world' Szenarien anlehnen.