till/managarten
1
0
Fork 0
mirror of https://github.com/Memo-2023/mana-monorepo.git synced 2026-05-14 19:41:09 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
managarten/docs/decisions/002-cluster-federation-architecture.md
Till JS 878424c003 feat: rename ManaCore to Mana across entire codebase 
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>
2026-04-05 20:00:13 +02:00

5.1 KiB
Raw Permalink Blame History

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

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.