Creating a service directory with Backstage.io

Introduction

Backstage is an open-source project launched by Spotify for building developer portals and service directories. Spotify created it originally and then donated it to the CNCF, who now hosts it as an incubating project. It helps organizations manage software development workflows and provides a centralized hub for services, documentation, and collaboration. Backstage consolidates all your infrastructure tooling, services, and documentation to create a streamlined development environment from end to end.

Backstage is an all-encompassing platform that provides various tools for overseeing software development projects. It includes:

• Backstage Software Catalog enables the management of all software, including microservices, libraries, data pipelines, websites, and ML models.
• Backstage Software Templates are invaluable for creating new projects quickly and aligning your tooling with your organization's most effective practices.
• Backstage TechDocs feature facilitates the creation, maintenance, retrieval, and utilization of technical documentation through a "docs like code" method.

Prerequisites

Check your system for the following prerequisites before beginning the tutorial. 

• node.js ≥ v18.12.0 installation
• curl or wget
• yarn Installation
• docker installation
• git installation‍

💡 This tutorial uses MacOS; For other operating systems use the set of commands compatible with your installers. For more details, check out Backstage official documentation.

Getting Started with Backstage

There are two ways to get started: clone the GitHub repo or install a NodeJS app. The former is slower but more straightforward. The latter is faster but might be more complex to troubleshoot.

Let’s discuss both ways:

Method 1: Clone Backstage repo

• Clone the Backstage GitHub repository: Open your terminal and run the below command.

• Run the below command to navigate the Backstage directory and install dependencies

• Start Backstage project locally

💡 This command will build and start Backstage with its required services

Method 2: Creating an application

• After Installing the prerequisites, you have to create an application by nodeJS. Note: You may receive errors while running this command due to installation dependencies. We’ll show you how to fix these errors in the next step. 

• Here is an example of the dependency error you may encounter while installing the application. If the application was successfully created, skip the next several steps and begin with starting Backstage.

• Run the below set of commands to debug those errors:

Expected output:

‍

• Change the directory for your required node version.

• Use the below command to create your first application.

Expected Output:

• We can see our demo1 application has been created.

• Run the below command to start your backstage on your local system.

‍

💡 Backstage will automatically launch in your browser. If not, paste the link (*HTTP://localhost:3000/*) in your browser to access the backstage.

Create a Service Directory

Backstage allows you to create a Service Directory to manage your services. Here's how you can create one:

• Click on the "Create Entity" button on the dashboard.
• Select "Service" as the entity or category type.

Create a New Component using a template

• Fill in the necessary information about your service, including its name, description, owner, and source code repository URL.
• Click "Create Service" to add the service to your directory.

Configure Backstage

Backstage offers complete control over your application's configuration, whether it’s customizing plugins or the overall look and feel. Plus, accessing the master file is a breeze with the simple command:

The above command allows you to configure Backstage. It will enable you to install plugins, connect third-party APIs, make changes to UI, and much more.

You can now fully explore your service directory, add additional services, customize the appearance, and integrate with various tools and services based on your needs. Backstage offers a multitude of plugins and extensions that can be combined with multiple tools, such as CI/CD, monitoring, and documentation systems.

For more in-depth information and examples, please refer to the comprehensive documentation available on the Backstage website.

Backstage will only check out the necessary files for the application. All other components are stored in a library.

Backstage Alternatives

With the growing demand for Internal developer platforms in the market, there is a need for Backstage alternatives depending on the personalized use cases of the companies. Hence, Let’s discuss a couple of top choices for Backstage:

Clutch

Clutch is an open-source alternative for Backstage. Lyft launched it, and it contains 1.5K Github stars. Clutch provides capabilities that can simplify operations and, in turn, improve your developer experience and operational capabilities. It comes with several out-of-the-box features for managing cloud-native infrastructure. It is designed to be organizational-specific and quickly teaches how to interact with whatever you run or wherever you run it.

‍

Kubiya

Kubiya is an internal developer platform that leverages conversational AI to implement all aspects of Platform Engineering. Dozens of action stores for popular engineering tools are used to parameterize standard and custom functions. Once the actions stores are set, developer teams simply converse their requests to Kubi, Kubiya’s 24x7 personal DevOps assistant. Kubi resides inside your existing chat tool, such as Slack. Generative AI and Large Language Models take over the repetitive tasks, making DevOps processes easily accessible to developers. Guardrails and templates control parameters and resourcing. Kubi can also answer simple questions based on documentation or trigger events with runbooks and gain visibility into services.

The benefits of Kubiya is that it is easy to set up, works from your existing chat tool, so there’s no ramp-up or context switching, it comes with built-in access control, audit trail, and observability, and is easy to customize and extend. Also, all the integrations are pre-built, so you don’t have to spend time creating them yourself. 

Conclusion 

Backstage is a powerful open-source platform enabling organizations to effectively manage their software development workflows. Backstage simplifies overseeing software development projects with comprehensive tools and features, including the Software Catalog, Software Templates, and TechDocs. Backstage creates a streamlined development environment that promotes collaboration and efficiency by unifying infrastructure tooling, services, and documentation. Whether creating a service directory or customizing your development environment, Backstage offers the flexibility and extensibility to meet your specific needs. Explore the possibilities of Backstage and unlock your software development projects' full potential by starting with Backstage today.

For more information and detailed examples, refer to the comprehensive documentation available on the Backstage website.

‍