mirror of https://github.com/Memo-2023/mana-monorepo.git synced 2026-05-14 21:41:09 +02:00

Till JS 3c91691d26 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.

2026-04-08 12:30:33 +02:00

7.8 KiB

Raw Blame History

Port Schema

⚠️ ASPIRATIONAL — does not match running services as of 2026-04-08.

This document describes a planned reorganization of port assignments into clean ranges (3000–3009 core, 3010–3019 infra, 3020–3029 AI/ML, …). 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.

Real ports today

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.

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

Originally drafted: 2026-03-28

Principles

Each range has a clear purpose (100 ports per range)
Backend 30xx and Frontend 50xx use matching last digits where possible
No conflicts - every port assigned exactly once
Room for growth in each range

3000-3009: Core Platform Services

Port	Service	Runtime	Description
3001	mana-auth	Hono/Bun	Authentication, JWT, sessions
3002	mana-credits	Go	Credit system, billing
3003	mana-subscriptions	Go	Stripe subscriptions
3004	mana-user	Go	User profiles, settings
3005	mana-analytics	Go	Usage analytics, DuckDB
3006-3009	(reserved)

3010-3019: Core Infrastructure Services

Port	Service	Runtime	Description
3010	mana-sync	Go	Local-first data sync (WebSocket + HTTP)
3011	mana-media	NestJS	Content-addressable storage, thumbnails
3012	mana-search	Go	Web search via SearXNG
3013	mana-notify	Go	Notifications (email, push, Matrix)
3014	mana-crawler	Go	Web crawler, content extraction
3015	mana-landing-builder	NestJS	Org landing page builder
3016	mana-api-gateway	Go	API keys, rate limiting, usage tracking
3017-3019	(reserved)

3020-3029: AI/ML Services

Port	Service	Runtime	Description
3020	mana-llm	Python	LLM abstraction (Ollama, OpenRouter)
3021	mana-stt	Python	Speech-to-Text (Whisper)
3022	mana-tts	Python	Text-to-Speech (Kokoro, Piper)
3023	mana-image-gen	Python	Image generation (FLUX)
3024	mana-voice-bot	Python	Voice-to-voice assistant
3025-3029	(reserved)

3030-3059: App Compute Servers

Only apps that need server-side compute (AI, external APIs, file operations). Pure CRUD apps use mana-sync directly.

Port	Service	Runtime	Description
3030	chat-server	Hono/Bun	AI chat, streaming, spaces
3031	todo-server	Hono/Bun	RRULE expansion, reminders
3032	calendar-server	Hono/Bun	CalDAV sync, Google Calendar, notifications
3033	contacts-server	Hono/Bun	Google Contacts, vCard import/export
3034	storage-server	Hono/Bun	S3 file ops, versioning, shares
3035	picture-server	Hono/Bun	Replicate AI, generation orchestration
3036	cards-server	Hono/Bun	AI card generation
3037	mukke-server	Hono/Bun	Audio processing, BPM, ID3 tags
3038	nutriphi-server	Hono/Bun	Gemini meal analysis
3039	planta-server	Hono/Bun	Gemini plant analysis
3040	presi-server	Hono/Bun	Share links
3041-3059	(reserved)

4000-4099: Matrix/Chat Stack

Port	Service	Description
4000	synapse	Matrix homeserver
4001	mana-matrix-bot	Go bot (health/metrics)
4010	element-web	Element web client
4011	matrix-web	SvelteKit Matrix client
4400	landings	Nginx static landing pages

5000-5059: Web Frontends (SvelteKit)

Port	Service	Corresponds to Server
5000	mana-web	Hub/Dashboard
5010	chat-web	3030 chat-server
5011	todo-web	3031 todo-server
5012	calendar-web	3032 calendar-server
5013	clock-web	(local-first only)
5014	contacts-web	3033 contacts-server
5015	storage-web	3034 storage-server
5016	presi-web	3040 presi-server
5017	nutriphi-web	3038 nutriphi-server
5018	zitare-web	(local-first only)
5019	photos-web	(local-first + mana-media)
5020	skilltree-web	(local-first only)
5021	picture-web	3035 picture-server
5022	citycorners-web	(local-first only)
5023	cards-web	3036 cards-server
5024	mukke-web	3037 mukke-server
5025	inventar-web	(local-first only)
5026	context-web	(local-first only)
5027	questions-web	(local-first only)
5028	planta-web	3039 planta-server
5029	moodlit-web	(future)
5030-5049	(reserved)

5050-5059: Playground/Dev Tools

Port	Service	Description
5050	llm-playground	LLM testing UI

5100-5199: Games

Port	Service	Description
5100	whopixels	Pixel art game

8000-8099: Monitoring Dashboards

Port	Service	Description
8000	grafana	Metrics dashboards
8010	umami	Web analytics
8020	glitchtip	Error tracking

9000-9199: Infrastructure & Exporters

Port	Service	Description
5432	postgres	PostgreSQL
6379	redis	Redis cache
9000	minio (S3 API)	Object storage
9001	minio (Console)	MinIO admin UI
9090	victoriametrics	Metrics storage
9091	pushgateway	Deploy metrics
9093	alertmanager	Alert routing
9095	alert-notifier	Matrix alert bridge
9100	node-exporter	Host metrics
9110	cadvisor	Container metrics
9121	redis-exporter	Redis metrics
9187	postgres-exporter	Postgres metrics

SearXNG (Internal Only)

Port	Service	Description
8080	searxng	Meta-search (not exposed to host)

Adding a New Service

Pick the next free port in the appropriate range
Update this document
Update docker-compose.macmini.yml
Update scripts/generate-env.mjs if the service has a dev env
Update docker/prometheus/prometheus.yml if the service exposes metrics

7.8 KiB Raw Blame History Unescape Escape