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

[kajukabla]

Summary

deploy/compose/run.sh assembles its docker compose invocation from explicit -f flags (compose.yml plus the conditional caddy/dev overlays). Passing any explicit -f disables Compose's automatic compose.override.yml loading, so operators currently have no way to layer site-local overrides — a compose.override.yml sitting in the directory is silently ignored.

This adds a BUZZ_COMPOSE_EXTRA_FILES environment switch: 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 instead of a mid-command docker compose failure.

Real-world motivation: staging the relay on a shared ML box needed memory caps on the relay container, which today requires re-running docker update after every ./run.sh upgrade. With this change the cap lives in a small override file and survives upgrades:

# deploy/compose/compose.limits.yml
services:
  relay:
    mem_limit: 2g

BUZZ_COMPOSE_EXTRA_FILES=compose.limits.yml ./run.sh start

Changes

• deploy/compose/run.sh — parse BUZZ_COMPOSE_EXTRA_FILES (colon- or space-separated), validate each path exists, append as -f flags after the built-in files; document the switch in ./run.sh help
• deploy/compose/README.md — new "Site-local overrides" section with the resource-limit example and a note that explicit -f flags are why compose.override.yml is not auto-loaded

Testing

• bash -n run.sh syntax check
• Functional test with a stubbed docker on PATH asserting exact flags:
  • baseline (no var): -f compose.yml unchanged
  • colon-separated: -f compose.yml -f /tmp/x-limits.yml -f /tmp/x-labels.yml
  • space-separated: same result
  • missing file: exits 1 with BUZZ_COMPOSE_EXTRA_FILES entry not found: ...
  • combined with BUZZ_COMPOSE_TLS=true: extra file appended after compose.caddy.yml
• just ci — all recipes pass except mobile-test, which fails on one pre-existing widget test (ChannelDetailPage keeps follow mode off while a tall newest message stays visible, mobile/test/features/channels/channel_detail_page_test.dart:1042). It fails identically on clean main (7e9b77f) and this PR touches only deploy/compose/, so it is unrelated.

🤖 Generated with Claude Code