April 17, 2023

Installing Backstage on a Mac

If you haven't heard about it before, Backstage is "an open platform for building developer portals". From my naive perspective, at its core it provides a dynamic service catalogue which leverages configuration that you check into Git. It was started by Spotify but is now an open source project.

I've been exploring the potential to integrate SquaredUp with Backstage recently. In order to understand Backstage better I wanted to install, configure, and run it on my local Macbook.

I followed the getting started guide on the Backstage website. My experience wasn't all smooth sailing, I ran into a couple of speed bumps which took time to resolve. In this blog I want to share what I learned to hopefully make your Backstage set-up seamless.

NOTE: This guide is specifically for MacOS. These steps should mostly work for Linux but if you are using Windows you will need to adjust the steps accordingly. I did not find any official documentation on how to run Backstage from PowerShell, but you could fall back to using WSL (the Windows Subsystem for Linux) if needed.

Before you begin

To get Backstage up and running you will need to install the following:

Node.js LTS (version 16 / gallium)

NOTE: An "LTS" (long term service) version of a product is a version which will continue to be supported for the foreseeable future. Node.js has many LTS versions.

This was the first speed bump I ran into. I had the LTS version 18 (hydrogen) installed on my Mac, but Backstage requires you to have LTS version 16 (gallium). At first I went ahead and tried to install Backstage with hydrogen installed, but quickly ran into errors which others had also hit online. The universal advice was to use gallium.

However, I didn't want to uninstall Node version 18 and go back to 16. I need the latest version for my SquaredUp plugin development. So how can I have multiple versions of Node.js running on my Mac? And how can I easily switch between them?

The answer I found was a utility called NVM (the Node Version Manager). NVM lets you install as many versions of Node as you want and to switch between them with one command.

To install NVM follow the instructions on the website. My Mac didn't have wget installed so I used the curl command to download the files:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

Then to install it:

export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Once it's installed you can check which versions of Node you currently have installed by using the nvm -ls command.

With nvm installed you can install the version 16 LTS version (gallium) with the command:

nvm install --lts=gallium

And now switch to it:

nvm use lts/gallium

Double check that you are using the correct version of Node.js using the command:

node --version

Note that each new terminal session will revert to your default version of Node.js. You will either need to change your default version to gallium or re-enter these commands to switch to it each time you want to run Backstage.

Yarn

Yarn is an alternative to NPM for managing your Node.js packages (originally developed by Meta). The official documentation omits the "sudo" command but I found that it failed to run on my Mac due to permissions issues without it:

sudo npm install --global yarn

Installing and running Backstage

With the preparation done, it should be fairly straightforward to get Backstage up and running.

Firstly, it's very important that the file path to where you want your Backstage project to be does not have any spaces! This particular issue blocked me for a day. I went down (false) rabbit holes thinking there was an issue running Backstage on M1 Mac's, but I was wrong.

# This is bad
/Users/stephentownshend/Code Projects/

# This is good
/Users/stephentownshend/Code/

Navigate to where you want to install backstage and submit the command:

npx @backstage/create-app

It will ask you to provide a name for your project. For example, I called mine "backstage-demo". It will go ahead and create a folder with the Backstage project inside of it. This will take some time to complete! Give it a good 5-10 minutes.

When it's done, you should have your Backstage installation ready to go:

To run Backstage enter the command:

yarn dev

This will run both the back-end and front-end processes and automatically open your web browser at http://localhost:3000

Summary

This is really just getting you to the start line. We haven't configured Backstage in any way to meet our own needs, deployed it in a scalable way, or connected it to our Git projects. I look forward to figuring this out and providing more guides in the near future.