From 14099cc42cae17f864230e63e4201bb2ef7e2322 Mon Sep 17 00:00:00 2001 From: Till JS Date: Sat, 28 Mar 2026 03:02:12 +0100 Subject: [PATCH] docs(infra): add PORT_SCHEMA.md + update Prometheus scrape targets Comprehensive port schema documentation as single source of truth. All services assigned to logical ranges: - 3000-3009: Core platform (auth, credits, subscriptions, user, analytics) - 3010-3019: Core infra (sync, media, search, notify, crawler, gateway) - 3020-3029: AI/ML (llm, stt, tts, image-gen, voice-bot) - 3030-3059: App backends - 4000-4099: Matrix stack - 5000-5059: Web frontends - 8000-8099: Monitoring - 9000-9199: Infrastructure exporters All port conflicts resolved. Prometheus targets updated to match. Co-Authored-By: Claude Opus 4.6 (1M context) --- docker/prometheus/prometheus.yml | 28 +++--- docs/PORT_SCHEMA.md | 155 +++++++++++++++++++++++++++++++ 2 files changed, 169 insertions(+), 14 deletions(-) create mode 100644 docs/PORT_SCHEMA.md diff --git a/docker/prometheus/prometheus.yml b/docker/prometheus/prometheus.yml index 753ce3288..d4479a2f7 100644 --- a/docker/prometheus/prometheus.yml +++ b/docker/prometheus/prometheus.yml @@ -82,14 +82,14 @@ scrape_configs: # Contacts Backend - job_name: 'contacts-backend' static_configs: - - targets: ['contacts-backend:3034'] + - targets: ['contacts-backend:3033'] metrics_path: '/metrics' scrape_interval: 30s # Storage Backend - job_name: 'storage-backend' static_configs: - - targets: ['storage-backend:3035'] + - targets: ['storage-backend:3034'] metrics_path: '/metrics' scrape_interval: 30s @@ -98,7 +98,7 @@ scrape_configs: # Nutriphi Backend - job_name: 'nutriphi-backend' static_configs: - - targets: ['nutriphi-backend:3037'] + - targets: ['nutriphi-backend:3038'] metrics_path: '/metrics' scrape_interval: 30s @@ -113,21 +113,21 @@ scrape_configs: # Mukke Backend - job_name: 'mukke-backend' static_configs: - - targets: ['mukke-backend:3010'] + - targets: ['mukke-backend:3037'] metrics_path: '/metrics' scrape_interval: 30s # Planta Backend - job_name: 'planta-backend' static_configs: - - targets: ['planta-backend:3022'] + - targets: ['planta-backend:3039'] metrics_path: '/metrics' scrape_interval: 30s # Picture Backend - job_name: 'picture-backend' static_configs: - - targets: ['picture-backend:3040'] + - targets: ['picture-backend:3035'] metrics_path: '/metrics' scrape_interval: 30s @@ -138,21 +138,21 @@ scrape_configs: # Mana LLM Gateway (Ollama + Google Fallback) - job_name: 'mana-llm' static_configs: - - targets: ['mana-llm:3025'] + - targets: ['mana-llm:3020'] metrics_path: '/metrics' scrape_interval: 15s # Mana Search Service - job_name: 'mana-search' static_configs: - - targets: ['mana-search:3020'] + - targets: ['mana-search:3012'] metrics_path: '/metrics' scrape_interval: 30s # Mana Media Service - job_name: 'mana-media' static_configs: - - targets: ['mana-media:3015'] + - targets: ['mana-media:3011'] metrics_path: '/metrics' scrape_interval: 30s @@ -210,35 +210,35 @@ scrape_configs: # API Gateway (Go) - job_name: 'mana-api-gateway' static_configs: - - targets: ['mana-api-gateway:3060'] + - targets: ['mana-api-gateway:3016'] metrics_path: '/metrics' scrape_interval: 15s # Matrix Bot (Go) — consolidated 21 bots - job_name: 'mana-matrix-bot' static_configs: - - targets: ['mana-matrix-bot:4000'] + - targets: ['mana-matrix-bot:4001'] metrics_path: '/metrics' scrape_interval: 30s # Sync Server (Go) — local-first data sync - job_name: 'mana-sync' static_configs: - - targets: ['mana-core-sync:3051'] + - targets: ['mana-core-sync:3010'] metrics_path: '/metrics' scrape_interval: 30s # Notification Service (Go) — email, push, matrix, webhook - job_name: 'mana-notify' static_configs: - - targets: ['mana-core-notify:3042'] + - targets: ['mana-core-notify:3013'] metrics_path: '/metrics' scrape_interval: 30s # Crawler Service (Go) - job_name: 'mana-crawler' static_configs: - - targets: ['mana-crawler:3023'] + - targets: ['mana-crawler:3014'] metrics_path: '/metrics' scrape_interval: 30s diff --git a/docs/PORT_SCHEMA.md b/docs/PORT_SCHEMA.md new file mode 100644 index 000000000..bd017f020 --- /dev/null +++ b/docs/PORT_SCHEMA.md @@ -0,0 +1,155 @@ +# Port Schema + +Canonical port assignments for all ManaCore services. This is the single source of truth. + +**Last updated:** 2026-03-28 + +## Principles + +1. Each range has a clear purpose (100 ports per range) +2. Backend 30xx and Frontend 50xx use matching last digits where possible +3. No conflicts - every port assigned exactly once +4. 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 Backends + +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-backend | NestJS | AI chat, streaming, spaces | +| 3031 | todo-server | Hono/Bun | RRULE expansion, reminders | +| 3032 | calendar-backend | NestJS | CalDAV sync, Google Calendar, notifications | +| 3033 | contacts-backend | NestJS | Google Contacts, vCard import/export | +| 3034 | storage-backend | NestJS | S3 file ops, versioning, shares | +| 3035 | picture-backend | NestJS | Replicate AI, generation orchestration | +| 3036 | manadeck-backend | NestJS | AI card generation | +| 3037 | mukke-backend | NestJS | Audio processing, BPM, ID3 tags | +| 3038 | nutriphi-backend | NestJS | Gemini meal analysis | +| 3039 | planta-backend | NestJS | 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 Backend | +|------|---------|----------------------| +| 5000 | mana-web | Hub/Dashboard | +| 5010 | chat-web | 3030 chat-backend | +| 5011 | todo-web | 3031 todo-server | +| 5012 | calendar-web | 3032 calendar-backend | +| 5013 | clock-web | *(local-first only)* | +| 5014 | contacts-web | 3033 contacts-backend | +| 5015 | storage-web | 3034 storage-backend | +| 5016 | presi-web | 3040 presi-server | +| 5017 | nutriphi-web | 3038 nutriphi-backend | +| 5018 | zitare-web | *(local-first only)* | +| 5019 | photos-web | *(local-first + mana-media)* | +| 5020 | skilltree-web | *(local-first only)* | +| 5021 | picture-web | 3035 picture-backend | +| 5022 | citycorners-web | *(local-first only)* | +| 5023 | manadeck-web | 3036 manadeck-backend | +| 5024 | mukke-web | 3037 mukke-backend | +| 5025 | inventar-web | *(local-first only)* | +| 5026 | context-web | *(local-first only)* | +| 5027 | questions-web | *(local-first only)* | +| 5028 | planta-web | 3039 planta-backend | +| 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 + +1. Pick the next free port in the appropriate range +2. Update this document +3. Update `docker-compose.macmini.yml` +4. Update `scripts/generate-env.mjs` if the service has a dev env +5. Update `docker/prometheus/prometheus.yml` if the service exposes metrics