Learn Backstage - Installation & Initial Bootstrap

#Introduction

In episode 2, you got to know Backstage's architecture: the monorepo, the five core primitives, and the frontend and backend systems. Now it's time to prove that it all runs. Episode 3 walks you through installation and initial bootstrap — creating your first Backstage application from the official template, running it on your machine, and understanding the basic configuration that comes with it. Make sure everything from episode 0 is installed before continuing.

#Bootstrapping with create-app

The most official way to get started is the create-app command. Just run:

npx @backstage/create-app@latest

This command downloads the official template from the npm registry, then asks for the application name you want. That name becomes the generated directory's name and the identity in package.json. When the process finishes, you have a Backstage application that can be run right away.

#Directory Structure

The generated output has a structure similar to the architecture described in episode 2:

Before running anything, install all dependencies with yarn install from the root directory. Yarn will sync the entire workspace according to yarn.lock.

#Running the Dev Server

#The yarn dev Command

For development mode, run a single command from the root:

yarn dev

yarn dev runs the frontend and backend together. The port conventions are:

#Verifying the http://localhost:3000 Page

Once the process finishes, open your browser and visit http://localhost:3000. You'll see the main Backstage page with a sidebar on the left. The backend can be checked at http://localhost:7007, which responds with a normal status. If both pages respond, the bootstrap was successful.

#Initial Configuration

#app-config.yaml

Every Backstage installation is controlled by app-config.yaml. This file holds the application title, base URL, port, and integrations. The app section controls the frontend; the backend section controls the server. You already saw a snippet in episode 2 — now this is the file controlling your instance.

#app-config.local.yaml — Local Overrides

app-config.local.yaml is a companion to app-config.yaml created specifically for local environments. It holds settings that override default values — for example, the development base URL or local credentials. The key point: this file is usually not committed to Git, so personal settings don't leak into the shared repository.

app:
  title: Backstage Dev Local
  baseUrl: http://localhost:3000
 
backend:
  baseUrl: http://localhost:7007
  listen:
    port: 7007

app-config.local.yaml is loaded after app-config.yaml, so its values win when both mention the same key.

#Environment Variables

Backstage supports pulling values from environment variables directly inside the configuration file. You do this by writing the variable name in dollar-brace syntax in the config value, as shown in the following example:

app:
  baseUrl: ${APP_BASE_URL}
backend:
  baseUrl: ${BACKEND_BASE_URL}

The variable values are set in the shell before running yarn dev:

export APP_BASE_URL=http://localhost:3000
export BACKEND_BASE_URL=http://localhost:7007
yarn dev

This pattern is handy when you switch between development and production environments without manually editing the config file.

#Conclusion

In this episode 3, you completed the bootstrap: creating an application with the create-app command, understanding the generated directory structure, running the dev server with yarn dev, verifying the pages on ports 3000 and 7007, and understanding app-config.yaml, app-config.local.yaml, and environment variables.

The key takeaways:

• yarn dev is the key command for development — frontend and backend run at the same time.
• Frontend on port 3000, backend on port 7007 — two pages for one application.
• app-config.local.yaml overrides app-config.yaml for local purposes.
• Environment variables can be referenced directly from within the configuration file.

In the next episode, episode 4, we dive into the most important primitive: Software Catalog basics — what an entity is, the eight kinds Backstage recognizes, and how catalog-info.yaml describes your services.