Added docker troubleshooting tips and code highlighting

Signed-off-by: Andre Wanlin <awanlin@spotify.com>

docs/deployment/docker.md

@@ -39,7 +39,7 @@ package with `yarn build:backend`.
 
 In a CI workflow it might look something like this, from the root:
 
-```bash
+```sh
 yarn install --frozen-lockfile
 
 # tsc outputs type definitions to dist-types/ in the repo root, which are then consumed by the build
@@ -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.
@@ -124,7 +126,7 @@ With the project built and the `.dockerignore` and `Dockerfile` in place, we are
 now ready to build the final image. From the root of the repo, execute the
 build:
 
-```bash
+```sh
 docker image build . -f packages/backend/Dockerfile --tag backstage
 ```
 
@@ -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
+```