Merge branch 'backstage:master' into refine-custom-permissions-doc

docs/deployment/docker.md

@@ -53,7 +53,7 @@ yarn build:backend --config ../../app-config.yaml
 Once the host build is complete, we are ready to build our image. The following
 `Dockerfile` is included when creating a new app with `@backstage/create-app`:
 
-```Dockerfile
+```dockerfile
 FROM node:18-bookworm-slim
 
 # Install isolate-vm dependencies, these are needed by the @backstage/plugin-scaffolder-backend.
@@ -74,8 +74,10 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
 USER node
 
 # This should create the app dir as `node`.
-# If it is instead created as `root` then the `tar` command below will fail: `can't create directory 'packages/': Permission denied`.
-# If this occurs, then ensure BuildKit is enabled (`DOCKER_BUILDKIT=1`) so the app dir is correctly created as `node`.
+# If it is instead created as `root` then the `tar` command below will
+# fail: `can't create directory 'packages/': Permission denied`.
+# If this occurs, then ensure BuildKit is enabled (`DOCKER_BUILDKIT=1`)
+# so the app dir is correctly created as `node`.
 WORKDIR /app
 
 # This switches many Node.js dependencies to production mode.
@@ -158,7 +160,7 @@ host build.
 The following `Dockerfile` executes the multi-stage build and should be added to
 the repo root:
 
-```Dockerfile
+```dockerfile
 # Stage 1 - Create yarn install skeleton layer
 FROM node:18-bookworm-slim AS packages
 
@@ -229,8 +231,10 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
 USER node
 
 # This should create the app dir as `node`.
-# If it is instead created as `root` then the `tar` command below will fail: `can't create directory 'packages/': Permission denied`.
-# If this occurs, then ensure BuildKit is enabled (`DOCKER_BUILDKIT=1`) so the app dir is correctly created as `node`.
+# If it is instead created as `root` then the `tar` command below will
+# fail: `can't create directory 'packages/': Permission denied`.
+# If this occurs, then ensure BuildKit is enabled (`DOCKER_BUILDKIT=1`)
+# so the app dir is correctly created as `node`.
 WORKDIR /app
 
 # Copy the install dependencies from the build stage and context
@@ -321,3 +325,16 @@ an NGINX image is available in the
 Note that if you're building a separate docker build of the frontend you
 probably need to adjust `.dockerignore` appropriately. Most likely by making
 sure `packages/app/dist` is not ignored.
+
+## Troubleshooting Tips
+
+When building Docker images you may run into problems from time to time, there are two handy flags you can use to help:
+
+- `--progress=plain`: this will give you a more verbose output and not fold the logs into sections. This is very useful when have an error but it just shows you the last command and possibly an exit code. Using this flag you are more likely to see where the error actually is.
+- `--no-cache`: this will rebuild all the layers every time. This is helpful when you want to be sure that it's building from scratch.
+
+Here's an example of these flags in use:
+
+```sh
+docker image build . -f packages/backend/Dockerfile --tag backstage --progress=plain --no-cache
+```

docs/features/kubernetes/installation.md

@@ -130,7 +130,7 @@ export class CustomClustersSupplier implements KubernetesClustersSupplier {
 
   static create(refreshInterval: Duration) {
     const clusterSupplier = new CustomClustersSupplier();
-    // setup refresh, e.g. using a copy of https://github.com/backstage/backstage/blob/master/plugins/search-backend-node/src/runPeriodically.ts
+    // setup refresh, e.g. using a copy of https://github.com/backstage/backstage/blob/master/plugins/kubernetes-backend/src/service/runPeriodically.ts
     runPeriodically(
       () => clusterSupplier.refreshClusters(),
       refreshInterval.toMillis(),

docs/getting-started/configuration.md

@@ -275,8 +275,8 @@ otherwise something went terribly wrong.
 
   ![Software template main screen, with a blue button to add an existing component](../assets/getting-started/b-existing-1.png)
 
-- As URL use `https://github.com/backstage/demo/blob/master/catalog-info.yaml`.
-  This is used by our [demo site](https://demo.backstage.io).
+- As URL use `https://github.com/backstage/backstage/blob/master/catalog-info.yaml`.
+  This is used in our [demo site](https://demo.backstage.io) catalog.
 
   ![Register a new component wizard, asking for an URL to the existing component YAML file](../assets/getting-started/b-existing-2.png)
 
@@ -285,7 +285,7 @@ otherwise something went terribly wrong.
   ![Register a new component wizard, showing the metadata for the component YAML we use in this tutorial](../assets/getting-started/b-existing-3.png)
 
 - You should receive a message that your entities have been added.
-- If you go back to `Home`, you should be able to find `demo`. You should be
+- If you go back to `Home`, you should be able to find `backstage`. You should be
   able to click it and see the details
 
 ## Create a new component using a software template

docs/getting-started/index.md

@@ -26,7 +26,7 @@ you to use the [Contributors](https://github.com/backstage/backstage/blob/master
   On MacOS, you will want to have run `xcode-select --install` to get the XCode command line build tooling in place.
 - An account with elevated rights to install the dependencies
 - `curl` or `wget` installed
-- Node.js [Active LTS Release](https://nodejs.org/en/blog/release/) installed using one of these
+- Node.js [Active LTS Release](https://nodejs.org/en/about/previous-releases) installed using one of these
   methods:
   - Using `nvm` (recommended)
     - [Installing nvm](https://github.com/nvm-sh/nvm#install--update-script)

docs/overview/versioning-policy.md

@@ -158,7 +158,7 @@ package export.
 
 The Backstage project uses [Node.js](https://nodejs.org/) for both its development
 tooling and backend runtime. In order for expectations to be clear we use the
-following schedule for determining the [Node.js releases](https://nodejs.org/en/about/releases/) that we support:
+following schedule for determining the [Node.js releases](https://nodejs.org/en/about/previous-releases) that we support:
 
 - At any given point in time we support exactly two adjacent even-numbered
   releases of Node.js, for example v12 and v14.

docs/plugins/backend-plugin.md

@@ -41,9 +41,11 @@ standalone mode. You can do a first-light test of your service:
 
 ```sh
 cd plugins/carmen-backend
-yarn start
+LEGACY_BACKEND_START=true yarn start
 ```
 
+> Note: `LEGACY_BACKEND_START=true` is needed while we transition fully to the [New Backend System](../backend-system/index.md). The templates have not been migrated yet; you can track this in [issue 21288](https://github.com/backstage/backstage/issues/21288)
+
 This will think for a bit, and then say `Listening on :7007`. In a different
 terminal window, now run