followup: hardcoded docker-compose.apple.yml references diverge from macOS overlay path

[yasinBursali]

Context

The runtime compose resolver (dream-server/scripts/resolve-compose-stack.sh) is being updated so that on Darwin hosts it selects installers/macos/docker-compose.macos.yml instead of docker-compose.apple.yml. This matches what the macOS installer writes into .compose-flags — the macOS-specific overlay sets llama-server replicas: 0 (native Metal), adds the llama-server-ready sidecar, and routes dashboard-api via host.docker.internal.

After that fix lands, four other call sites still hardcode docker-compose.apple.yml. They are pre-existing — not regressions introduced by the resolver fix — but they represent the same class of macOS/Linux overlay divergence and should be tracked.

Files

Runtime code path (highest risk):

• dream-server/scripts/bootstrap-upgrade.sh:275 — fallback branch in dream update / model hot-swap, fires when .compose-flags is missing or unreadable on the install dir. On a stale macOS install (or after manual deletion of .compose-flags), this branch will select the Linux-style overlay and break the same way the resolver did.

Declarative / catalog entries (lower risk — describe repo contents):

• dream-server/scripts/classify-hardware.sh:80 — tier-to-overlays lookup table, still emits docker-compose.apple.yml for the apple key.
• dream-server/manifest.json:58 — project manifest lists docker-compose.apple.yml among the shipped files. Does not select it at runtime, but divergent if installers/macos/docker-compose.macos.yml is the authoritative macOS overlay.
• dream-server/config/hardware-classes.json:121,136 — two entries set "compose_overlays": ["docker-compose.base.yml", "docker-compose.apple.yml"] for Apple-Silicon hardware classes.

Why these weren't folded into the resolver PR

• bootstrap-upgrade.sh is simultaneously being modified in another open PR (bootstrap-upgrade hardening — filename arg, docker-group detection, JSON body escaping). Touching :275 in two PRs at once would cause an avoidable merge collision.
• The catalog/declarative references are the harder question: they describe what the repo contains rather than what is selected at runtime. Changing them has downstream effects on classification and packaging code and needs its own verification pass.

Recommended approach

1. Land the resolver fix first.
2. In a follow-up PR, update bootstrap-upgrade.sh:275 (coordinate with whatever bootstrap-upgrade PR is currently in flight so the two land in sequence).
3. In a separate (or same) follow-up, decide the structural question: does DreamServer keep two apple compose overlays (one for Docker-only testing, one for real macOS installs), or does it consolidate to a single overlay and let the installer vs runtime path converge? If consolidation, update classify-hardware.sh, manifest.json, and hardware-classes.json accordingly and delete the now-dead file.

Verification steps for the follow-up

• Static: rg 'docker-compose\.apple\.yml' dream-server/ should either return zero real (non-test, non-comment) hits on the macOS runtime path, or only references to a consolidated overlay.
• Runtime: on a macOS host, rm -f .compose-flags && dream update must not pull the Linux-style docker-compose.apple.yml — it should fall through either to the resolver (fixed) or to a corrected fallback.

Impact

• macOS (Apple Silicon): affected — stale-cache or fallback code paths still diverge until this follow-up lands.
• Linux (NVIDIA/AMD): unaffected — docker-compose.apple.yml remains a legitimate file for CI runs with --gpu-backend apple.
• Windows/WSL2: unaffected — inherits Linux behavior.

[yasinBursali]

Status check from integration test of PR stack Light-Heart-Labs#893–909

Environment: WSL2 / Ubuntu 24.04 / NVIDIA RTX 3070 Laptop / Tier 1
Branch tested: local/integration-test containing all 17 open yasinBursali PRs merged --no-ff onto Light-Heart-Labs/DreamServer@c0600ca
Install: bash install.sh --all --non-interactive --no-comfyui → phase 13, 17 healthy containers

Verdict (Linux side)

The resolver part is fixed by PR Light-Heart-Labs#897. No Linux regression. The other 4 hardcoded sites listed in this followup are still pending.

Evidence — Linux runtime selects nvidia overlay only

Ran the resolver directly on this WSL2/Linux host after fresh install of the integration branch:

$ bash dream-server/scripts/resolve-compose-stack.sh
-f docker-compose.base.yml -f docker-compose.nvidia.yml -f extensions/services/ape/compose.yaml -f extensions/services/dashboard/compose.local.yaml -f extensions/services/dreamforge/compose.yaml -f extensions/services/embeddings/compose.yaml -f extensions/services/litellm/compose.yaml -f extensions/services/litellm/compose.local.yaml -f extensions/services/n8n/compose.yaml -f extensions/services/open-webui/compose.local.yaml -f extensions/services/openclaw/compose.yaml -f extensions/services/openclaw/compose.local.yaml -f extensions/services/perplexica/compose.yaml -f extensions/services/perplexica/compose.local.yaml -f extensions/services/privacy-shield/compose.yaml -f extensions/services/privacy-shield/compose.local.yaml -f extensions/services/qdrant/compose.yaml -f extensions/services/searxng/compose.yaml -f extensions/services/token-spy/compose.yaml -f extensions/services/tts/compose.yaml -f extensions/services/whisper/compose.yaml -f extensions/services/whisper/compose.nvidia.yaml

Filtered for any apple/macos overlay leak:

$ bash dream-server/scripts/resolve-compose-stack.sh | tr ' ' '\n' | grep -E "macos|apple"
(none)

The nvidia overlay is selected, the Linux extensions overlays are merged, and neither docker-compose.macos.yml nor docker-compose.apple.yml appears in the Linux output. The PR Light-Heart-Labs#897 IS_DARWIN = platform.system() == "Darwin" gating works correctly: on a Linux host, the new installers/macos/docker-compose.macos.yml selection branch is dead code, so the change introduces zero risk for Linux/WSL2.

Static check of the 4 followup sites — all 4 still need attention

rg 'docker-compose\.apple\.yml' dream-server/ on the integration branch (which includes PR Light-Heart-Labs#897):

dream-server/scripts/bootstrap-upgrade.sh:275  ← runtime fallback path, this is the high-risk one per the issue body
dream-server/scripts/classify-hardware.sh:80   ← tier-to-overlays lookup table
dream-server/manifest.json:58                  ← project manifest
dream-server/config/hardware-classes.json:121
dream-server/config/hardware-classes.json:136  ← two entries for Apple-Silicon hardware classes

So PR Light-Heart-Labs#897 fixes the resolver but does not touch the four sites this followup specifically calls out. They're still hardcoded on the integration branch. The followup is still required.

Note on bootstrap-upgrade.sh:275 and the in-flight bootstrap PR

This issue notes:

bootstrap-upgrade.sh is simultaneously being modified in another open PR (bootstrap-upgrade hardening — filename arg, docker-group detection, JSON body escaping). Touching :275 in two PRs at once would cause an avoidable merge collision.

That PR is Light-Heart-Labs#898 — also merged into the integration branch I tested. PR Light-Heart-Labs#898 modifies bootstrap-upgrade.sh extensively (60+ lines) but does NOT touch the docker-compose.apple.yml reference at line 275. So the followup change to :275 would NOT collide with Light-Heart-Labs#898 if filed against the post-Light-Heart-Labs#898 base. The merge collision the followup was trying to avoid doesn't exist anymore — it would just be a clean follow-up commit on top.

What was NOT tested

• The macOS-side runtime path (no Apple hardware in this environment). The installers/macos/docker-compose.macos.yml selection branch on Darwin hosts is verified by static review only — see PR fix(resolve-compose-stack): select macOS overlay on Darwin hosts Light-Heart-Labs/DreamServer#897's static review comments.

Cross-reference

None of my findings filed during this test pass (#331-#335) interact with the resolver. PR Light-Heart-Labs#897 is the cleanest pass in the whole stack from a Linux/runtime perspective.

---

Filed during full-stack integration test of open PR stack Light-Heart-Labs#893–909 on Light-Heart-Labs/DreamServer@c0600ca3.

[yasinBursali]

Addressed by PR Light-Heart-Labs#918 (currently draft, pending upstream review).