fix(mana-image-gen): align source default port with production reality

Source default was 3026 but Mac Mini production has been overriding to
3025 via the launchd plist in scripts/mac-mini/setup-image-gen.sh ever
since the service was set up. The override existed in exactly one place
that is not version-controlled in any obvious way — anyone redeploying
without that script would land on 3026 and clients pointing at 3025
would fail to connect.

Source default → 3025 across main.py, setup.sh, README, CLAUDE.md so the
launchd plist is no longer load-bearing. The Mac Mini setup script still
sets PORT=3025 explicitly; that's now belt-and-suspenders rather than the
only thing keeping production alive.

Also added a note clarifying that this Mac Mini service (flux2.c, MPS,
arm64-only) is *not* the same thing as the "image-gen" running on the
Windows GPU server (PyTorch + diffusers + CUDA, port 3023, code lives at
C:\mana\services\mana-image-gen\ outside this repo). Two different
implementations sharing a name was confusing the port-collision audit.

Updated docs/PORT_SCHEMA.md warning block to retract the previous false
claims of two active port collisions:

  - image-gen ↔ video-gen on 3026 — wrong: image-gen runs on Mac Mini
    on 3025 (now also the source default), video-gen is alone on the
    Windows GPU on 3026
  - voice-bot ↔ sync on 3050 — latent only: mana-voice-bot is not
    deployed anywhere (no launchd, no scheduled task, no cloudflared
    route), so the collision is in source defaults but not in production

The voice-bot 3050 default should still be moved before voice-bot is
ever deployed — flagged in the PORT_SCHEMA warning instead of silently
fixed since voice-bot deployment is its own decision.
This commit is contained in:
Till JS 2026-04-08 12:30:33 +02:00
parent b0a08ce239
commit 3c91691d26
5 changed files with 58 additions and 30 deletions

View file

@ -4,23 +4,43 @@
>
> This document describes a *planned* reorganization of port assignments
> into clean ranges (30003009 core, 30103019 infra, 30203029 AI/ML, …).
> The reorg has not been executed: the actual ports the services bind to
> live in their `app/main.py` / `start.sh` / `config.ts` and currently
> follow a different scheme. Per-service ports are documented in each
> `services/*/CLAUDE.md`. Notable real-world ports today:
> The reorg has not been executed: the actual ports services bind to
> live in their `app/main.py` / `start.sh` / `config.ts`. Per-service
> ports are documented in each `services/*/CLAUDE.md`.
>
> - mana-auth `3001`, mana-credits `3061`, mana-user `3062`,
> mana-subscriptions `3063`, mana-analytics `3064`, mana-events `3065`
> - mana-media `3015`, mana-sync `3050`, mana-search `3021`,
> mana-notify `3040`, mana-crawler `3023`
> - mana-llm `3025`, mana-stt `3020`, mana-tts `3022`,
> mana-image-gen `3026`, mana-video-gen `3026` ⚠️ **collision**,
> mana-voice-bot `3050` ⚠️ **collision with mana-sync**
> ### Real ports today
>
> Two real port collisions exist (image-gen ↔ video-gen, voice-bot ↔ sync)
> that are masked by the fact that they don't all run on the same host
> today. Either execute the reorg below, or pick non-colliding ports and
> update this doc to match reality.
> **Mac Mini:**
> - mana-auth `3001`
> - mana-stt `3020` (Mac Mini local instance, MLX)
> - mana-image-gen `3025` (Mac Mini, flux2.c, MPS — separate from the
> Windows GPU image-gen on `gpu-img.mana.how` which lives outside the repo)
> - mana-sync `3050`
> - mana-search `3021`, mana-notify `3040`, mana-crawler `3023`,
> mana-media `3015`
> - mana-credits `3061`, mana-user `3062`, mana-subscriptions `3063`,
> mana-analytics `3064`, mana-events `3065`
>
> **Windows GPU server (`192.168.178.11`):**
> - mana-llm `3025`
> - mana-stt `3020`
> - mana-tts `3022`
> - image-gen (Windows variant, **not the repo's `mana-image-gen`**) `3023`
> - mana-video-gen `3026`
> - Ollama `11434`
>
> ### No production collisions today, but two latent ones in source defaults
>
> | Latent collision | Why it doesn't bite | What to watch for |
> |---|---|---|
> | mana-image-gen and mana-llm both use `3025` | Different machines (Mac Mini vs Windows GPU); mana-image-gen `setup.sh` hard-fails outside macOS arm64 so it can't be deployed onto the Windows GPU by accident | Don't try to run mana-image-gen and mana-llm on the same host |
> | mana-voice-bot defaults to `3050`, mana-sync also `3050` | mana-voice-bot is not deployed anywhere yet (no launchd plist, no Scheduled Task, no cloudflared route) | Pick a free port for mana-voice-bot before deploying it — current default will collide with mana-sync wherever sync runs |
>
> The previous version of this warning claimed two **active** collisions
> (image-gen ↔ video-gen on 3026, voice-bot ↔ sync on 3050). That was
> wrong: image-gen on Mac Mini was overridden to 3025 via a launchd plist
> (now also the source default — see commit history), and voice-bot isn't
> running anywhere.
**Originally drafted:** 2026-03-28