Skip to main content
In this lesson we cover how to configure a Backstage instance and which files to modify to change Backstage behavior across environments (local development, production, etc.). This guide explains the layered configuration model used by Backstage and shows where to place environment-specific overrides. A typical Backstage app repository contains configuration files such as app-config.local.yaml, app-config.production.yaml, app-config.yaml, backstage.json, and catalog-info.yaml, along with folders like node_modules, packages, and plugins.
A slide titled "Backstage Configuration" showing a directory tree of config files and folders. It lists files like app-config.local.yaml, app-config.production.yaml, app-config.yaml, backstage.json, catalog-info.yaml and folders such as node_modules, packages, plugins, etc.
Key configuration files to know:
  • app-config.yaml — base configuration shared across environments
  • app-config.local.yaml — overrides for local development
  • app-config.production.yaml — overrides for production deployments
Backstage supports layered configuration: the base app-config.yaml contains settings common to all environments, and environment-specific files merge on top of it to override values when present.

​
How the config files work (layered configuration)

  • Backstage loads app-config.yaml first as the canonical base.
  • If present, app-config.local.yaml and app-config.production.yaml are merged on top of the base and replace any overlapping keys.
  • Only include keys in the override files for properties that change between environments; unspecified keys remain as defined in the base file.

​
app-config.yaml (base configuration)

Put values that are identical across environments here. This file should be committed to source control and serve as the canonical configuration for your Backstage instance.

​
app-config.local.yaml (local development overrides)

Use app-config.local.yaml to override only the values that differ for local development. Backstage merges this file on top of the base config, so you don’t need to repeat the entire configuration—only the keys you want to change.
A diagram showing that app-config.local.yaml (local development configuration) overrides the main app-config.yaml, with an arrow labeled "Override" from the local file to the main config.
Example local overrides:
Do not commit app-config.local.yaml if it contains secrets (API keys, credentials) or machine-specific values. Keep it as a local-only configuration file and add it to .gitignore where appropriate.

​
app-config.production.yaml (production overrides)

app-config.production.yaml works the same as the local override file but is intended for production deployments. Use environment-specific overrides here and avoid hard-coding secrets or machine-specific values in files stored in version control.
A diagram titled "App-config.production.yaml" showing a PROD server icon above two config-file icons (app-config.yaml on the left and app-config.production.yaml on the right) with a horizontal arrow labeled "Override" pointing from the production-specific file to the base config.
Example: reference environment variables instead of committing secrets. The example below uses an environment variable for the host:
Use environment variables in production configs to avoid storing secrets in version control. The HOST environment variable in the example above will be substituted at runtime.

​
Restarting Backstage after config changes

Backstage reads configuration files at startup. After editing any config file, restart your Backstage process so the new settings are applied.

​
Quick reference table

​
Summary

  • app-config.yaml is the shared base config; commit this file.
  • app-config.local.yaml provides local development overrides—keep sensitive values out of version control.
  • app-config.production.yaml contains production-specific overrides and should rely on environment variables for secrets.
  • Backstage merges the base and override files at startup; restart the process to load configuration changes.
Further reading and references:

Watch Video