docs: updated to reflect new --config flags

docs/conf/index.md

@@ -15,11 +15,11 @@ allowing for customization.
 
 ## Supplying Configuration
 
-Configuration is stored in `app-config.yaml` files, with support for suffixes
-such as `app-config.production.yaml` to override values for specific
-environments. The configuration files themselves contain plain YAML, but with
-support for loading in secrets from various sources using for example `$env` and
-`$file` keys.
+Configuration is stored in YAML files where the defaults are `app-config.yaml`
+and `app-config.local.yaml` for local overrides. Other sets of files can by
+loaded by passing `--config <path>` flags. The configuration files themselves
+contain plain YAML, but with support for loading in secrets from various sources
+using for example `$env` and `$file` keys.
 
 It is also possible to supply configuration through environment variables, for
 example `APP_CONFIG_app_baseUrl=https://staging.example.com`. However these

docs/conf/writing.md

@@ -55,20 +55,28 @@ picked up by the serve tasks of `@backstage/cli` for local development, and are
 injected by the entrypoint of the nginx container serving the frontend in a
 production build.
 
-## File Resolution
+## Configuration Files
 
 It is possible to have multiple configuration files, both to support different
 environments, but also to define configuration that is local to specific
-packages.
+packages. The configuration files to load are selected using a `--config <path>`
+flag, and it is possible to load any number of files. Paths are relative to the
+working directory of the executed process, for example `package/backend`. This
+means that to select a config file in the repo root when running the backend,
+you would use `--config ../../my-config.yaml`.
 
-All `app-config.yaml` files inside the monorepo root and package root are
-considered, as are files with additional `local` and environment affixes such as
-`development`, for example `app-config.local.yaml`,
-`app-config.production.yaml`, and `app-config.development.local.yaml`. Which
-environment config files are loaded is determined by the `APP_ENV` environment
-variable, or `NODE_ENV` if it is not set. Local configuration files are always
-loaded, but are meant for local development overrides and should typically be
-`.gitignore`'d.
+If no `config` flags are specified, the default behavior is to load
+`app-config.yaml` and, if it exists, `app-config.local.yaml` from the repo root.
+In the provided project setup, `app-config.local.yaml` is `.gitignore`'d, making
+it a good place to add config overrides and secrets for local development.
+
+Note that if any config flags are provided, the default `app-config.yaml` files
+are NOT loaded. To include them you need to explicitly include them with a flag,
+for example:
+
+```
+yarn start --config ../../app-config.yaml --config ../../app-config.staging.yaml
+```
 
 All loaded configuration files are merged together using the following rules:
 
@@ -84,10 +92,10 @@ order:
 
 - Configuration from the `APP_CONFIG_` environment variables has the highest
   priority, followed by files.
-- Files inside package directories have higher priority than those in the root
-  directory.
-- Files with environment affixes have higher priority than ones without.
-- Files with the `local` affix have higher priority than ones without.
+- Files loaded with config flags are ordered by priority, where the last flag
+  has the highest priority.
+- If no config flags are provided, `app-config.local.yaml` has higher priority
+  than `app-config.yaml`.
 
 ## Secrets
 

docs/support/project-structure.md

@@ -228,9 +228,6 @@ future.
 - [`app-config.yaml`](https://github.com/spotify/backstage/tree/master/app-config.yaml) -
   Configuration for the app, both frontend and backend
 
-- [`app-config.development.yaml`](https://github.com/spotify/backstage/tree/master/app-config.development.yaml) -
-  Used for overriding configuration when developing locally.
-
 - [`catalog-info.yaml`](https://github.com/spotify/backstage/tree/master/catalog-info.yaml) -
   Description of Backstage in the Backstage Entity format.
 

plugins/kubernetes-backend/examples/dice-roller/README.md

@@ -23,7 +23,7 @@ This can be used to run the kubernetes plugin locally against a mock service.
 6. Register existing component in Backstage
    - https://github.com/mclarke47/dice-roller/blob/master/catalog-info.yaml
 
-Update `app-config.development.yaml` as follows.
+Add or update `app-config.local.yaml` with the following:
 
 ```yaml
 kubernetes:
@@ -45,4 +45,4 @@ Mac copy to clipboard:
 kubectl get secret $(kubectl get sa dice-roller -o=json | jq -r .secrets[0].name) -o=json | jq -r '.data["token"]' | base64 --decode | pbcopy
 ```
 
-Paste into `app-config.development.yaml` `kubernetes.clusters[0].serviceAccountToken`
+Paste into `app-config.local.yaml` `kubernetes.clusters[0].serviceAccountToken`