How to Install Backstage on Windows 11 Using Ubuntu 22.04 (WSL) – Complete Step-by-Step Guide

 

Introduction

Backstage is an open-source developer portal platform created by Spotify that helps organizations manage software catalogs, documentation, CI/CD pipelines, cloud resources, and developer workflows from a single interface.

If you're running Windows 11 and want to install Backstage using Ubuntu 22.04 through Windows Subsystem for Linux (WSL), this comprehensive guide will walk you through the entire setup process.

By the end of this tutorial, you'll have a fully functional Backstage application running locally on your Windows 11 machine.

---

Prerequisites

Before starting, ensure you have:

• Windows 11 installed

• Ubuntu 22.04 configured in WSL

• Administrator access on Windows

• Stable internet connection

• At least 8 GB RAM recommended

---

Step 1: Login to Windows 11

Log in to your Windows 11 system using an account with administrator privileges.

Administrator access is required to install software and configure Docker.

---

Step 2: Open Ubuntu 22.04 in WSL

Launch Ubuntu 22.04 from the Start Menu or run the following command from PowerShell:

wsl -d Ubuntu-22.04

You should now be inside your Ubuntu terminal.

---

Step 3: Update Ubuntu Packages

Update all package repositories and upgrade installed packages.

sudo apt update && sudo apt upgrade -y

This ensures your environment is running the latest security patches and package versions.

---

Step 4: Create a Project Workspace

Create a dedicated directory for your projects.

mkdir -p ~/eduarn-projects
cd ~/eduarn-projects

This keeps your Backstage installation organized and easy to manage.

---

Step 5: Install Docker

Backstage often integrates with containerized environments, making Docker an important dependency.

Install Docker using:

curl -fsSL https://get.docker.com | sudo sh

Wait for the installation to complete.

---

Step 6: Configure Docker Permissions

Add your current user to the Docker group.

sudo usermod -aG docker $USER

This allows Docker commands to run without requiring sudo.

Note: You may need to restart your terminal session for group changes to take effect.

---

Step 7: Verify Docker Installation

Check the installed Docker version.

docker --version

Test Docker functionality:

sudo docker run hello-world

If the container runs successfully, Docker is correctly installed.

---

Step 8: Install NVM (Node Version Manager)

Backstage requires Node.js. NVM makes Node version management easier.

Install NVM:

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

Reload your shell:

source ~/.bashrc

Verify installation:

nvm --version

---

Step 9: Install Node.js 22

Install the latest supported Node.js version.

nvm install 22
nvm use 22

Verify installation:

node -v
npm -v

You should see the installed Node.js and npm versions displayed.

---

Step 10: Install Yarn

Backstage uses Yarn as its package manager.

Enable Corepack and install Yarn:

corepack enable
yarn set version stable

Verify Yarn installation:

yarn -v

---

Step 11: Install Required Build Tools

Install essential development tools and dependencies.

sudo apt install -y build-essential python3 make g++

These packages are required for compiling native modules during installation.

---

Step 12: Create a New Backstage Application

Navigate to your projects directory:

cd ~/eduarn-projects

Create a new Backstage application:

npx @backstage/create-app@latest

When prompted for the application name, enter:

eduarn-backstage

The Backstage scaffolding process may take several minutes depending on your internet speed.

---

Step 13: Navigate to the Backstage Directory

Move into the newly created application folder:

cd eduarn-backstage

---

Step 14: Start Backstage

Launch the Backstage development server.

yarn start

The initial startup may take several minutes as dependencies are compiled.

Once completed, you will see messages indicating the application is running.

---

Step 15: Access Backstage in Your Browser

Open your preferred browser and navigate to:

http://localhost:3000

You should now see the Backstage Developer Portal running successfully on your Windows 11 machine.

---

Common Troubleshooting Tips

Docker Permission Denied

If Docker returns permission errors:

newgrp docker

or restart Ubuntu and try again.

---

Node Version Issues

Verify that Node.js 22 is active:

node -v

If needed:

nvm use 22

---

Port 3000 Already in Use

Identify the process:

sudo lsof -i :3000

Stop the process or configure Backstage to use another port.

 

---

Benefits of Using Backstage

Backstage provides:

• Centralized developer portal

• Service catalog management

• Documentation management

• Kubernetes integration

• CI/CD visibility

• Software templates

• Developer productivity improvements

• Internal developer platform capabilities

Organizations worldwide use Backstage to standardize software development and improve developer experience.

---

Conclusion

Installing Backstage on Windows 11 using Ubuntu 22.04 WSL is a straightforward process when the proper prerequisites are installed. By configuring Docker, Node.js 22, Yarn, and the required build tools, you can quickly launch a fully functional Backstage Developer Portal for local development and experimentation.

Following the steps outlined in this guide will help you create a stable and production-ready development environment for Backstage.

---

Training and Support

Looking to master Backstage, DevOps, Kubernetes, Docker, Cloud, or Platform Engineering?

Eduarn Training Services

✔ Retail Training Programs

✔ Corporate Training Programs

✔ Hands-on Labs and Real-Time Projects

✔ Industry Expert Trainers

✔ Customized Enterprise Learning Solutions

Visit: www.eduarn.com

For training, consulting, and corporate workshops, contact us through www.eduarn.com.