Skip to main content
Configuring Backstage involves adjusting a few YAML files to control behavior across different environments—development, staging, and production. This guide walks you through the three primary configuration files you’ll find in a standard Backstage project:
  • app-config.yaml
  • app-config.local.yaml
  • app-config.production.yaml
You’ll learn each file’s role, how they merge, and best practices for managing sensitive data.

​
Configuration Overview

Config FileEnvironmentPurpose
app-config.yamlAllShared defaults for every deployment
app-config.local.yamlLocal developmentOverrides for your local machine
app-config.production.yamlProductionOverrides for live, production instances

​
1. app-config.yaml

This is the base configuration loaded in every environment. Put settings here that do not change between development, staging, and production, such as your app title, organization name, and common backend options. Example app-config.yaml: 
app:
  title: "Scaffolded Backstage App"
  baseUrl: http://147.182.170.10:3000

organization:
  name: "My Company"

backend:
  baseUrl: http://147.182.170.10:7007
  listen:
    port: 7007
  cors:
    origin: http://147.182.170.10:3000
    methods: [GET, HEAD, PATCH, POST, PUT, DELETE]
    credentials: true

​
2. app-config.local.yaml

Use this file for local development overrides. When you run yarn dev, Backstage merges these settings on top of app-config.yaml so you can point to localhost endpoints and use personal API keys.
app-config.local.yaml merges with (and overrides) the base settings in app-config.yaml—ideal for local tweaks.
Example app-config.local.yaml: 
app:
  baseUrl: http://localhost:3000

backend:
  baseUrl: http://localhost:7007
  cors:
    origin: http://localhost:3000
Do not commit app-config.local.yaml to version control—it may contain sensitive credentials or machine-specific settings.

​
3. app-config.production.yaml

Define production-specific overrides here. Backstage will merge this file with app-config.yaml when running in a production mode (e.g., NODE_ENV=production yarn start).
app-config.production.yaml replaces or extends base settings for your live environment.
You can reference environment variables (e.g., ${HOST}) to avoid hard-coding secrets.
Example snippet: 
app:
  baseUrl: https://${HOST}

backend:
  baseUrl: https://${HOST}:7007
  cors:
    origin: https://${HOST}

​
Reloading Configuration

Backstage reads configuration only at startup. After editing any YAML file, restart your server to apply changes: 
# Stop the running instance
CTRL+C

# Restart in development mode
yarn dev
In production, you might use: 
NODE_ENV=production yarn start
Always restart or reload your process manager after config updates to ensure Backstage picks up the latest settings.

Watch Video