From 26a668e22314d4eb56c54a14f1281bfe816290b2 Mon Sep 17 00:00:00 2001 From: val Date: Fri, 21 Nov 2025 17:42:22 +0000 Subject: [PATCH] added paragraph on overriding the compose.yml --- docs/operators/handbook.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/operators/handbook.md b/docs/operators/handbook.md index 71bf20baf..462c35847 100644 --- a/docs/operators/handbook.md +++ b/docs/operators/handbook.md @@ -320,6 +320,36 @@ If you need to run a command within a running container you can use `abra app ru If you need to run a command on a container that won't start (eg. the container is stuck in a restart loop) you can temporarily disable its default entrypoint by setting it in `compose.yml` to something like ['tail', '-f', '/dev/null'], then redeploy the stack (with `--force --chaos` so you don't need to commit), then [get into the now running container](#how-do-i-attach-to-a-running-container), do your business, and when done revert the compose.yml change and redeploy again. +## How can I modify/override the `compose.yml-file`? + +If you need a customization of the `compose`-file, e.g., override a specific, hard coded value that is not present in the sample-env, add a custom volume, or add an environment variable that the image knows but which is not (yet) included in the `compose.yml` of the recipe, you can do so by using the `COMPOSE_FILE` environment variable ([more details in Docker docs](https://docs.docker.com/compose/how-tos/environment-variables/envvars/#compose_file)). + +For details about how the two compose files are merged, consult the official [Docker docs](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/). + +If it's not a special or edge case, perhaps consider modifying the original recipe / racing a feature request so everyone can benefit from your conceptual work? + +### Example +The upstream image of your `app` allows you to modify the SMTP port with an environment variable called `SMTP_PORT`, but the recipe's maintainers didn't include it in the compose file because they didn't have in mind anyone would need a non-standard port. So you can't simply add `SMTP_PORT` to your `yourapp.example.com.env`, because it won't find its way into the running container. + +For a quick fix, you could now create a file, e.g. `yourapp.example.com.compose.override.yml` (naming is up to you) with the content: + +``` +services: + app: + environment: + SMTP_PORT: 25 +``` + +and add to your `yourapp.example.com.env` + +``` +COMPOSE_FILE="compose.yml:../../servers//yourapp.example.com.compose.override.yml +``` +_Make sure you include the original `compose.yml` and place the `yourapp.domain.compose.override.yml` directly alongside of your `yourapp.example.com.env`, or change the (relative) path respectively._ + +This will now add/overwrite the `SMTP_PORT` environment variable of the `app` container. + +` ## Can I run Co-op Cloud on ARM? `@Mayel`: