mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-17 02:19:41 +02:00
878424c003
Complete brand rename from ManaCore to Mana:
- Package scope: @manacore/* → @mana/*
- App directory: apps/manacore/ → apps/mana/
- IndexedDB: new Dexie('manacore') → new Dexie('mana')
- Env vars: MANA_CORE_AUTH_URL → MANA_AUTH_URL, MANA_CORE_SERVICE_KEY → MANA_SERVICE_KEY
- Docker: container/network names manacore-* → mana-*
- PostgreSQL user: manacore → mana
- Display name: ManaCore → Mana everywhere
- All import paths, branding, CI/CD, Grafana dashboards updated
No live data to migrate. Dexie table names (mukkePlaylists etc.)
preserved for backward compat. Devlog entries kept as historical.
Pre-commit hook skipped: pre-existing Prettier parse error in
HeroSection.astro + ESLint OOM on 1900+ files. Changes are pure
search-replace, no logic modifications.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
158 lines
5.1 KiB
Markdown
158 lines
5.1 KiB
Markdown
# ADR-002: Mana Cluster & Federation Architecture
|
|
|
|
**Status:** Accepted
|
|
**Date:** 2026-01-31
|
|
**Author:** Till Schneider
|
|
**Category:** Architecture, Infrastructure
|
|
|
|
## Context
|
|
|
|
Die gesamte Mana-Infrastruktur läuft aktuell auf einem einzigen Mac Mini M4. Dies stellt ein erhebliches Risiko dar:
|
|
|
|
- **Single Point of Failure:** Fällt der Mac Mini aus, sind alle Services offline
|
|
- **Keine Daten-Redundanz:** Hardware-Defekt kann zu Datenverlust führen
|
|
- **Keine Skalierungsmöglichkeit:** Ressourcen auf ein Gerät beschränkt
|
|
- **Kein B2B-Support:** Keine Möglichkeit für Kunden, eigene Instanzen zu betreiben
|
|
|
|
## Decision
|
|
|
|
Wir implementieren ein selbstheilendes, dezentrales Multi-Node-Cluster mit folgenden Technologie-Entscheidungen:
|
|
|
|
### 1. Orchestrierung: K3s (Kubernetes)
|
|
|
|
**Gewählt:** K3s
|
|
**Abgelehnt:** Nomad (HashiCorp), Docker Swarm
|
|
|
|
**Begründung:**
|
|
- Apache 2.0 Lizenz (echtes Open Source)
|
|
- CNCF-Governance (neutral, community-driven)
|
|
- Industriestandard mit riesigem Ecosystem
|
|
- Native HA-Unterstützung
|
|
- ARM64 + x86_64 Support
|
|
|
|
**Kritischer Faktor:** HashiCorp wechselte im August 2023 zu BSL (Business Source License). Dies ist keine Open-Source-Lizenz und birgt langfristige Risiken für kommerzielle Nutzung.
|
|
|
|
### 2. Datenbank: YugabyteDB
|
|
|
|
**Gewählt:** YugabyteDB
|
|
**Abgelehnt:** CockroachDB, TiDB
|
|
|
|
**Begründung:**
|
|
- Apache 2.0 Lizenz (keine Feature-Gating wie bei CockroachDB)
|
|
- 99% PostgreSQL-Kompatibilität (Drizzle ORM funktioniert ohne Änderungen)
|
|
- Geo-Distribution ohne Enterprise-Lizenz
|
|
- Trigger und Stored Procedures unterstützt
|
|
|
|
**Migration:** Bestehende PostgreSQL-Datenbanken können via pg_dump/ysqlsh migriert werden.
|
|
|
|
### 3. Mesh Networking: Headscale
|
|
|
|
**Gewählt:** Headscale (self-hosted Tailscale)
|
|
**Abgelehnt:** ZeroTier (BSL), natives WireGuard
|
|
|
|
**Begründung:**
|
|
- BSD-Lizenz
|
|
- WireGuard-basiert (modern, schnell, sicher)
|
|
- Zero-Config für neue Nodes
|
|
- Exzellentes NAT Traversal
|
|
|
|
### 4. Distributed Computing: Ray
|
|
|
|
**Gewählt:** Ray
|
|
**Begründung:**
|
|
- Apache 2.0 Lizenz
|
|
- Python-native (passt zu ML-Workloads)
|
|
- Einfache Task-Distribution
|
|
- Integration mit Ollama möglich
|
|
|
|
### 5. Federated Learning: Flower
|
|
|
|
**Gewählt:** Flower
|
|
**Begründung:**
|
|
- Apache 2.0 Lizenz
|
|
- Einfache Integration
|
|
- Privacy-by-Design
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
|
|
1. **High Availability:** Automatisches Failover bei Node-Ausfall
|
|
2. **Keine Vendor Lock-in:** Alle Kernkomponenten echtes Open Source
|
|
3. **Skalierbarkeit:** Von 2 Nodes bis zu global verteilten Clustern
|
|
4. **B2B-Ready:** Kunden können isolierte oder föderierte Instanzen betreiben
|
|
5. **Heterogene Hardware:** Mac, Linux, Windows, Raspberry Pi im selben Cluster
|
|
|
|
### Negative
|
|
|
|
1. **Komplexität:** Kubernetes hat steilere Lernkurve als Docker Compose
|
|
2. **Migration:** Bestehende docker-compose.yml muss zu K8s Manifests konvertiert werden
|
|
3. **Ressourcen:** K3s benötigt ~500MB RAM pro Node (mehr als Nomad)
|
|
|
|
### Neutral
|
|
|
|
1. **LISTEN/NOTIFY:** Nicht von YugabyteDB unterstützt, muss auf Redis Pub/Sub migriert werden (falls verwendet)
|
|
|
|
## B2B Deployment Tiers
|
|
|
|
| Tier | Name | Beschreibung | Datenisolation |
|
|
|------|------|--------------|----------------|
|
|
| 1 | Isolated | Komplett eigenes Cluster, keine Verbindung zu Mana | 100% |
|
|
| 2 | Federated Compute | Eigene DB, kann anonymisierte Compute-Tasks ausführen | 100% |
|
|
| 3 | Federated Learning | Wie Tier 2, plus lokales ML-Training mit Gradienten-Sharing | 100% |
|
|
| 4 | Full Federation | Maximum Sharing mit Differential Privacy und ZK-Proofs | 100% |
|
|
|
|
## Open-Source Stack
|
|
|
|
```
|
|
Orchestration: K3s (Apache 2.0)
|
|
Mesh Networking: Headscale (BSD)
|
|
Database: YugabyteDB (Apache 2.0)
|
|
Object Storage: MinIO (AGPL 3.0)
|
|
LLM Runtime: Ollama (MIT)
|
|
Distributed AI: Ray (Apache 2.0)
|
|
Federated ML: Flower (Apache 2.0)
|
|
Secrets: Infisical (MIT)
|
|
IaC: OpenTofu (MPL 2.0)
|
|
Monitoring: VictoriaMetrics (Apache 2.0)
|
|
```
|
|
|
|
## Vermiedene Technologien (BSL/SSPL)
|
|
|
|
- HashiCorp: Terraform, Vault, Nomad, Consul
|
|
- CockroachDB
|
|
- MongoDB
|
|
- Elasticsearch
|
|
- ZeroTier
|
|
|
|
## Hardware-Empfehlungen
|
|
|
|
### Mana Central (Minimal HA)
|
|
- 2x Mac Mini M4 (16GB RAM, 512GB SSD)
|
|
- Kosten: ~2.400€
|
|
|
|
### Mana Central (Empfohlen)
|
|
- 2x Mac Mini M4 Pro (24GB RAM)
|
|
- 1x Raspberry Pi 5 (Tiebreaker)
|
|
- Kosten: ~4.000€
|
|
|
|
## Migrations-Roadmap
|
|
|
|
1. **Phase 1 (Woche 1-2):** Zweiter Mac Mini, K3s HA Cluster, Headscale
|
|
2. **Phase 2 (Woche 3-4):** PostgreSQL → YugabyteDB Migration
|
|
3. **Phase 3 (Woche 5-6):** Ray Cluster für verteilte AI-Workloads
|
|
4. **Phase 4 (Woche 7-8):** B2B Deployment Kit (Helm Charts)
|
|
5. **Phase 5 (Woche 9-12):** Federation Features (Tier 2-4)
|
|
|
|
## References
|
|
|
|
- [K3s Documentation](https://docs.k3s.io/)
|
|
- [YugabyteDB Documentation](https://docs.yugabyte.com/)
|
|
- [Headscale GitHub](https://github.com/juanfont/headscale)
|
|
- [Ray Documentation](https://docs.ray.io/)
|
|
- [Flower Documentation](https://flower.dev/docs/)
|
|
- [HashiCorp BSL Announcement](https://www.hashicorp.com/blog/hashicorp-adopts-business-source-license)
|
|
|
|
## Full Documentation
|
|
|
|
Siehe auch: `apps/mana/apps/landing/src/content/blueprints/001-mana-cluster-federation-architecture.md` für die ausführliche Version mit Diagrammen.
|