> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Backstage Configuration
> Guide to Backstage configuration files and layered environment-specific overrides for local and production using app-config.yaml, app-config.local.yaml and app-config.production.yaml
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`.
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.
```yaml theme={null}
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
```
## 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.
Example local overrides:
```yaml theme={null}
app:
baseUrl: http://localhost:3000
backend:
baseUrl: http://localhost:7007
cors:
origin: http://localhost:3000
```
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.
Example: reference environment variables instead of committing secrets. The example below uses an environment variable for the host:
```yaml theme={null}
app:
baseUrl: "https://${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.
```bash theme={null}
# Stop the server (Ctrl+C in most terminals), then restart:
yarn dev
```
## Quick reference table
| Config file | Purpose | Notes |
| ---------------------------- | --------------------------------------- | ---------------------------------------------------------------------- |
| `app-config.yaml` | Base configuration for all environments | Commit to repository; contains shared settings |
| `app-config.local.yaml` | Local development overrides | Only include keys that differ locally; do not commit secrets |
| `app-config.production.yaml` | Production overrides | Reference environment variables for secrets and deploy-specific values |
## 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:
* [Backstage Configuration documentation](https://backstage.io/docs/features/configuration)
* [YAML specification](https://yaml.org/spec/)