Skip to main content
Version: Next

Config-first development

Audience: Developers and Admins

Summary​

One of the things that makes Backstage easier to operate over time is treating configuration as the primary way to control application behavior. Instead of writing custom code for every change, many behaviors can be toggled, adjusted, or extended through configuration files.

By the end of this page, you will understand how Backstage configuration layering works and how to manage it across environments.

How configuration layering works​

Backstage loads configuration from multiple app-config*.yaml files and merges them together. Files loaded later override values from earlier files. The Docker image built in the first step starts with this command:

node packages/backend --config app-config.yaml --config app-config.production.yaml

This means app-config.production.yaml overrides any values set in app-config.yaml. You can use this pattern to keep your base config for local development and override only what changes in production.

Common configuration split​

FilePurpose
app-config.yamlBase configuration shared across all environments.
app-config.local.yamlLocal overrides, not committed to source control.
app-config.production.yamlProduction-specific overrides.

Environment variables in config​

Use the ${VAR_NAME} syntax to reference environment variables. This is the recommended approach for secrets and values that differ between environments:

app-config.production.yaml
backend:
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}

This keeps secrets out of your repository and lets the same Docker image be used across environments by changing the variables at deploy time.

What to configure vs. what to code​

A good rule of thumb: if a change affects where something connects, how it authenticates, or which features are enabled, it belongs in configuration. If it changes what a feature does, it belongs in code.

Examples of config-driven behavior:

  • Database connection details.
  • Authentication provider selection and credentials.
  • Catalog locations and entity providers.
  • Integration tokens (GitHub, GitLab, etc.).
  • TechDocs storage backend (local, S3, GCS, Azure).
  • Proxy endpoints for external services.

Making configuration your primary lever for environment differences simplifies your CI/CD pipeline. You build one Docker image and deploy it everywhere, varying only the config files and environment variables.

Further reading​

For the full configuration reference, see the Configuration documentation.

Next steps​

With your deployment running and configuration managed, you should set up monitoring to keep it healthy.