Containerized Backstage development: a clean, reproducible workflow

Introduction

Developing plugins or managing a Backstage instance often requires a complex toolchain (Node.js, yarn, and a variety of dependencies) all installed directly on your workstation. While this setup works, it can quickly lead to a cluttered system, version conflicts, and inconsistencies across different development environments. For users of immutable Linux distributions like Fedora Silverblue, this traditional approach can be even more challenging, as direct package installations are discouraged or restricted.

But what if you could develop, test, and iterate on your Backstage plugins or instance without installing any of these tools on your host machine?

With containerization, you can create isolated, reproducible environments that encapsulate everything Backstage needs (Node.js, yarn, and even databases) while keeping your workstation clean and your workflow consistent. This approach is ideal for Backstage developers who want to avoid dependency conflicts, streamline collaboration, or work seamlessly on immutable systems.

In this post, we’ll walk through how to set up a containerized Backstage development environment. You’ll learn how to use Docker or Podman to run your Backstage instance, develop plugins, and manage dependencies, all without touching your system’s global state. Whether you’re a Backstage maintainer, a plugin developer, or just exploring the platform, this guide will help you build a cleaner, more efficient workflow.

Prerequisites

  • Docker or Podman installed on your system
  • Basic familiarity with Dockerfiles and container concepts

Setting up a Containerized Environment for a blank Backstage instance

Save the following content to a file named Containerfile:

FROM node:22

RUN corepack enable && yarn set version 4.4.1

WORKDIR /app
ENTRYPOINT /bin/bash
EXPOSE 3000 7007

 

Build the image using the Containerfile:

podman build -t local-backstage-dev:latest .

 

Run the container with the current working directory mounted. The Backstage source code will be located in this directory:

podman run -it --rm -v `pwd`:/app -p 3000:3000 -p 7007:7007 localhost/local-backstage-dev:latest

 

This will drop you into a shell. From here, you can start following the getting started guide to bootstrap a Backstage instance.

Maintaining an Existing Instance

If you want to maintain an existing instance, you can use the same image from the previous section. Clone the source code of the instance and start working from there:

git clone ${INSTANCE_GIT_URL}
podman run -it --rm -v `pwd`:/app -p 3000:3000 -p 7007:7007 localhost/local-backstage-dev:latest

 

From this point, you can start upgrading, or migrating components of the instance.

Here are some examples of what you can do:

yarn install
yarn backstage-cli versions:bump
...

 

Maintaining a plugin

The same procedure applies when maintaining a plugin. Whether you start from a new Backstage instance or an existing one, you can launch the container from the instance directory and begin by creating a plugin.

If you want to contribute to an existing Backstage plugin in its own Git repository, such as this one, the process remains largely the same:

git clone [email protected]:gluobe/hetzner-backstage-plugin.git
podman run -it --rm -v `pwd`:/app -p 3000:3000 -p 7007:7007 localhost/local-backstage-dev:latest

 

From this point, you can upgrade dependencies, start a development server to work on the plugin, and more.

Conclusion

Containerizing your Backstage development workflow isn’t just about keeping your workstation clean, it’s about unlocking a more flexible, reproducible, and collaborative way to build and maintain your Backstage instance or plugins. By leveraging Docker or Podman, you can say goodbye to dependency conflicts, system clutter, and the headaches of setting up complex environments on immutable systems like Fedora Silverblue. It’s definitly not something to be afraid of, after building a very simple container with some sane defaults, we have the foundation to do everything from bootstrapping a new Backstage instance, to contributing to an existing Backstage plugin.

Menu