From 7583cce41fadc0cfcd5f1b6fce48de81787aa74b Mon Sep 17 00:00:00 2001
From: kajukabla <106099463+kajukabla@users.noreply.github.com>
Date: Sat, 1 Aug 2026 11:07:23 -0700
Subject: [PATCH] feat(deploy): support extra compose override files via
 BUZZ_COMPOSE_EXTRA_FILES

deploy/compose/run.sh passes explicit -f flags to docker compose, which
disables automatic compose.override.yml loading, so operators had no way
to layer site-local overrides (resource limits, labels, host tweaks)
without editing tracked files or re-running docker update after every
upgrade.

Add BUZZ_COMPOSE_EXTRA_FILES: a colon- or space-separated list of
compose files appended as additional -f flags after the built-in ones,
so operator values win the Compose merge. Missing entries fail fast
with a clear error. Documented in ./run.sh help and the deploy README.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: kajukabla <106099463+kajukabla@users.noreply.github.com>
---
 deploy/compose/README.md | 28 ++++++++++++++++++++++++++++
 deploy/compose/run.sh    | 18 ++++++++++++++++++
 2 files changed, 46 insertions(+)

diff --git a/deploy/compose/README.md b/deploy/compose/README.md
index 0de524fb5b..d1705eb8cf 100644
--- a/deploy/compose/README.md
+++ b/deploy/compose/README.md
@@ -23,6 +23,34 @@ The bootstrap script should eventually replace manual `.env` editing for normal
 users. It is responsible for generating stable secrets and, optionally, an owner
 keypair.
 
+## Site-local overrides
+
+`run.sh` passes explicit `-f` flags to `docker compose`, which disables
+Compose's automatic `compose.override.yml` loading. To layer your own override
+files (resource limits, extra labels, host-specific tweaks), set
+`BUZZ_COMPOSE_EXTRA_FILES` to a colon- or space-separated list of paths. They
+are appended after the built-in files, so your values win the Compose merge.
+Relative paths are resolved from `deploy/compose/`.
+
+For example, to cap relay memory on a shared host — instead of re-running
+`docker update` after every upgrade:
+
+```yaml
+# deploy/compose/compose.limits.yml
+services:
+  relay:
+    mem_limit: 2g
+```
+
+```bash
+BUZZ_COMPOSE_EXTRA_FILES=compose.limits.yml ./run.sh start
+```
+
+The extra files apply to every `run.sh` command, so set the variable
+persistently (e.g. in the shell profile of the deploy user) to keep `upgrade`
+and `restart` consistent with `start`. Use `./run.sh config` to verify the
+merged result.
+
 ## Production notes
 
 - Requires Docker Compose v2.24.4 or newer; the TLS override uses Compose's
diff --git a/deploy/compose/run.sh b/deploy/compose/run.sh
index d5465ea1f5..8b994bcb20 100755
--- a/deploy/compose/run.sh
+++ b/deploy/compose/run.sh
@@ -11,6 +11,20 @@ fi
 if [[ "${BUZZ_COMPOSE_DEV:-false}" == "true" ]]; then
   COMPOSE_FILES+=(-f compose.dev.yml)
 fi
+if [[ -n "${BUZZ_COMPOSE_EXTRA_FILES:-}" ]]; then
+  IFS=': ' read -r -a EXTRA_FILES <<<"${BUZZ_COMPOSE_EXTRA_FILES}"
+  for extra_file in "${EXTRA_FILES[@]}"; do
+    if [[ -z "${extra_file}" ]]; then
+      continue
+    fi
+    if [[ ! -f "${extra_file}" ]]; then
+      echo "BUZZ_COMPOSE_EXTRA_FILES entry not found: ${extra_file}" >&2
+      echo "Paths are resolved relative to deploy/compose/." >&2
+      exit 1
+    fi
+    COMPOSE_FILES+=(-f "${extra_file}")
+  done
+fi
 
 compose() {
   docker compose --env-file .env "${COMPOSE_FILES[@]}" "$@"
@@ -123,6 +137,10 @@ Commands:
 Environment switches:
   BUZZ_COMPOSE_TLS=true   Include compose.caddy.yml for automatic HTTPS
   BUZZ_COMPOSE_DEV=true   Include compose.dev.yml for local admin ports/tools
+  BUZZ_COMPOSE_EXTRA_FILES=<paths>
+                          Colon- or space-separated compose files appended
+                          after the built-in ones (site-local overrides such
+                          as resource limits win the Compose merge)
 MSG
     ;;
   *)