Add Lagoon Build Errors pages (#3608)

docs/using-lagoon-the-basics/docker-compose-yml.md

@@ -245,3 +245,33 @@ no such service: container:amazeeio-ssh-agent
 BuildKit is a toolkit for converting source code to build artifacts in an efficient, expressive and repeatable manner.
 
 With the release of Lagoon v2.11.0, Lagoon now provides support for more advanced BuildKit-based docker-compose builds. To enable BuildKit for your Project or Environment, add `DOCKER_BUILDKIT=1` as a build-time variable to your Lagoon project or environment.
+
+## Docker Compose Errors in Lagoon Builds
+
+See the [Lagoon Build Errors page](lagoon-build-errors-and-warnings.md#docker-compose-errors) for how to resolve common build errors with Docker Compose
+
+## Common Docker Compose Issues
+
+This section outlines some of the more common Docker Compose errors, and how to remedy them. These may present in local development, or as [Lagoon Build Errors and Warnings](lagoon-build-errors-and-warnings.md#docker-compose-errors)
+
+### Dual Mapping keys
+``` shell title="Docker Compose output indicating mapping key error"
+ERR: yaml: unmarshal errors: line 22: mapping key "<<" already defined at line 21
+```
+Early releases of the Lagoon examples contained a pair of YAML aliases attached to services to provide volumes and user code. Newer releases of Docker Compose will report this as an error. Whilst all examples have now been updated, there may be some older codebases around that need updating.
+
+This error arises from Docker Compose not knowing what it is inserting into the array, so just assuming it may be duplicate.
+
+If your docker-compose.yml contains one or more of this (or similar) code blocks, you will be affected.
+``` yaml title="Docker Compose error with dual mapping keys"
+...
+    << : [*default-volumes]
+    << : [*default-user]
+...
+```
+The corrected version combines both aliases into a single mapping key - you'll need to remedy all occurrances.
+``` yaml title="Docker Compose correct insertion of multiple alias mapping keys"
+...
+    << : [*default-volumes, *default-user]
+...
+```

docs/using-lagoon-the-basics/lagoon-build-errors-and-warnings.md

@@ -0,0 +1,24 @@
+# Lagoon Build Errors and Warnings
+
+Newer releases of Lagoon have the capability to identify build errors, and highlight them as warnings without failing the build. They should be resolved wherever possible, as future releases of Lagoon may not be able to handle the errors.
+
+If you aren't sure how to resolve these errors, please reach out to your Lagoon administrator, or ask a question in the [Lagoon community](../community/discord.md).
+
+## Docker Compose Errors
+
+Please also see the section on [Common Docker Compose Issues](docker-compose-yml.md#common-docker-compose-issues), as some of these issues may be covered there
+
+``` shell title="Lagoon Build output indicating env_file error"
+> an env_file is defined in your docker-compose file, but no matching file found
+```
+Docker Compose expects a referenced env file to be present at build time, but that env file is only present in local development, or has been excluded from the Dockerfile. The Lagoon team is working to hopefully allow Docker Compose to ignore this error, so this warning will remain until we have a resolution.
+
+``` shell title="Lagoon Build output indicating string key error"
+> an invalid string key was detected in your docker-compose file
+```
+There is an error in your Docker Compose file, most likely relating to a malformed or misused alias or anchor. The error message should help you understand where.
+
+``` shell title="Lagoon Build output indicating yaml validation error"
+> There are yaml validation errors in your docker-compose file that should be corrected
+```
+There is an error in your Docker Compose file, most likely relating to a malformed or misused alias or anchor. The error message should help you understand where.

mkdocs.yml

@@ -16,6 +16,7 @@ nav:
   - .lagoon.yml: using-lagoon-the-basics/lagoon-yml.md
   - docker-compose.yml: using-lagoon-the-basics/docker-compose-yml.md
   - Build and Deploy Process: using-lagoon-the-basics/build-and-deploy-process.md
+  - Lagoon Build Errors and Warnings: using-lagoon-the-basics/lagoon-build-errors-and-warnings.md
   - Going Live: using-lagoon-the-basics/going-live.md
 - Docker Images:
   - Commons: docker-images/commons.md
@@ -220,6 +221,8 @@ plugins:
   - search
   - redirects:
       redirect_maps:
+        'lagoon-build-errors.md': 'using-lagoon-the-basics/lagoon-build-errors-and-warnings.md'
+        'docker-compose-errors.md': 'using-lagoon-the-basics/lagoon-build-errors-and-warnings.md#docker-compose-errors'
         'lagoon/README.md': 'README.md'
         'lagoon/getting-started/README.md': 'README.md'
         'lagoon/using-lagoon-advanced/deploytarget_configs.md': 'using-lagoon-advanced/deploytarget-configs.md'