feat(deploy): support extra compose override files via BUZZ_COMPOSE_EXTRA_FILES

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

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
     ;;
   *)