Docker-Services Referenz¶

Sovereign MoE — Vollständige Service-Dokumentation
Basis: docker-compose.yml

Service-Übersicht¶

Container	Image / Build	Host-Port	Container-Port	Funktion
`langgraph-orchestrator`	`./Dockerfile`	`8002`	`8000`	LangGraph-Orchestrator, FastAPI, OpenAI-API
`mcp-precision`	`./mcp_server/Dockerfile`	`8003`	`8003`	MCP Precision Tools Server (16 determin. Tools)
`neo4j-knowledge`	`neo4j:5-community`	`7474`, `7687`	`7474`, `7687`	Knowledge Graph (GraphRAG + Ontologie)
`terra_cache`	`redis/redis-stack-server:latest`	`6379`	`6379`	Redis: Checkpoints, Caches, Performance-Scores
`chromadb-vector`	`chromadb/chroma:latest`	`8001`	`8000`	Vektordatenbank für semantisches Caching
`moe-kafka`	`confluentinc/cp-kafka:7.7.0`	`9092`	`9092`	Kafka Event-Streaming (KRaft, kein Zookeeper)
`moe-admin`	`./admin_ui/Dockerfile`	`8088`	`8088`	Admin UI: Konfiguration, User-Management
`moe-prometheus`	`prom/prometheus:latest`	`9090`	`9090`	Metriken-Scraper
`moe-grafana`	`grafana/grafana:latest`	`3001`	`3000`	Dashboards & Visualisierung
`node-exporter`	`prom/node-exporter:latest`	`9100`	`9100`	Host-Metriken (CPU, RAM, Disk, Netzwerk)
`cadvisor`	`gcr.io/cadvisor/cadvisor:latest`	`9338`	`8080`	Container-Ressourcen-Metriken

Service-Details¶

`langgraph-orchestrator`¶

Der Kern des Systems. Verarbeitet alle eingehenden Anfragen über eine LangGraph-Pipeline.

Build: ./Dockerfile (Python-App)
Port: 8002 (extern) → 8000 (intern)
Abhängigkeiten: terra_cache, chromadb-vector, mcp-precision, neo4j-knowledge, moe-kafka
Konfiguration: via .env-Datei (env_file)

Umgebungsvariablen (fest im compose):

Variable	Wert
`REDIS_URL`	`redis://terra_cache:6379`
`CHROMA_HOST`	`chromadb-vector`
`CHROMA_PORT`	`8000`
`MCP_URL`	`http://mcp-precision:8003`
`NEO4J_URI`	`bolt://neo4j-knowledge:7687`
`NEO4J_USER`	`neo4j`
`NEO4J_PASS`	`moe-sovereign`
`KAFKA_URL`	`kafka://moe-kafka:9092`
`DB_PATH`	`/app/userdb/users.db`

`mcp-precision`¶

MCP Precision Tools Server mit 16 deterministischen Berechnungs-Tools (kein LLM-Einsatz).

Build: ./mcp_server/Dockerfile
Port: 8003
Keine externen Abhängigkeiten

`neo4j-knowledge`¶

Knowledge Graph-Datenbank für GraphRAG. Speichert Entitäten und Relationen, die aus Systemantworten extrahiert werden.

Image: neo4j:5-community
Ports: 7474 (Browser UI), 7687 (Bolt-Protokoll)
Heap: initial 512 MB, max 1 GB
Pagecache: 512 MB

`terra_cache`¶

Redis Stack Server. Dient als zentraler Cache für LangGraph-Checkpoints, Expert-Performance-Scores, Plan-Cache, GraphRAG-Cache und User-API-Key-Cache.

Image: redis/redis-stack-server:latest
Port: 6379

`chromadb-vector`¶

Vektordatenbank für das semantische Caching von Anfragen und Antworten.

Image: chromadb/chroma:latest
Port: 8001 (extern) → 8000 (intern)
Telemetrie: deaktiviert (ANONYMIZED_TELEMETRY=FALSE)

`moe-kafka`¶

Kafka-Broker im KRaft-Modus (kein separater Zookeeper erforderlich). Verwaltet drei Topics für Event-Streaming.

Image: confluentinc/cp-kafka:7.7.0
Port: 9092
Modus: KRaft (Single-Broker)
Retention: 7 Tage oder 512 MB

`moe-admin`¶

Web-basierte Admin-Oberfläche für Systemkonfiguration und User-Management.

Build: ./admin_ui/Dockerfile
Port: 8088
Abhängigkeiten: langgraph-app, moe-prometheus, terra_cache
Docker-Socket: Lesezugriff auf /var/run/docker.sock (Container-Status)

`moe-prometheus`¶

Metriken-Scraper. Sammelt Metriken vom Orchestrator, Node-Exporter und cAdvisor.

Image: prom/prometheus:latest
Port: 9090
Retention: 90 Tage
Konfiguration: /opt/deployment/moe-sovereign/moe-infra/prometheus/prometheus.yml

`moe-grafana`¶

Visualisierungs-Dashboard auf Basis der Prometheus-Daten.

Image: grafana/grafana:latest
Port: 3001 (extern) → 3000 (intern)
Standard-Dashboard: moe-operations.json
Anonymer Zugang: deaktiviert

`node-exporter`¶

Exportiert Host-Metriken (CPU, RAM, Disk, Netzwerk) für Prometheus.

Image: prom/node-exporter:latest
Port: 9100
Zugriff: pid: host, bind-mounts auf /proc, /sys, /

`cadvisor`¶

Container-Ressourcen-Metriken für Docker-Container.

Image: gcr.io/cadvisor/cadvisor:latest
Port: 9338 (extern) → 8080 (intern)
Zugriff: privilegierter Modus, bind-mounts auf Docker-Verzeichnisse

Netzwerk-Topologie¶

Alle Services laufen im selben Docker-Netzwerk und kommunizieren über Container-Namen:

graph TD
    subgraph CLIENTS["Clients (extern)"]
        OW["Open WebUI"]
        CC["Claude Code"]
        CU["curl / SDK"]
    end

    subgraph CORE["Kern-Services"]
        ORCH["langgraph-orchestrator\n:8002"]
        ADMIN["moe-admin\n:8088"]
        MCP["mcp-precision\n:8003"]
    end

    subgraph STORAGE["Datenspeicher"]
        REDIS["terra_cache\n:6379"]
        CHROMA["chromadb-vector\n:8001"]
        NEO4J["neo4j-knowledge\n:7687/:7474"]
        KAFKA["moe-kafka\n:9092"]
    end

    subgraph OBS["Observability"]
        PROM["moe-prometheus\n:9090"]
        GRAF["moe-grafana\n:3001"]
        NODE["node-exporter\n:9100"]
        CADV["cadvisor\n:9338"]
    end

    CLIENTS -->|OpenAI API| ORCH
    ORCH --> REDIS & CHROMA & NEO4J & KAFKA & MCP
    ADMIN --> ORCH & PROM & REDIS
    PROM --> ORCH & NODE & CADV
    GRAF --> PROM

Volume-Mounts¶

Persistente Host-Verzeichnisse¶

Service	Host-Pfad	Container-Pfad	Zweck
`moe-kafka`	`/opt/moe-infra/kafka-data`	`/var/lib/kafka/data`	Kafka Log-Segmente
`neo4j-knowledge`	`/opt/moe-infra/neo4j-data`	`/data`	Neo4j Daten
`neo4j-knowledge`	`/opt/moe-infra/neo4j-logs`	`/logs`	Neo4j Logs
`terra_cache`	`/opt/moe-infra/redis-data`	`/data`	Redis Persistenz
`chromadb-vector`	`/opt/moe-infra/chroma-data`	`/chroma/chroma`	ChromaDB Vektordaten
`langgraph-orchestrator`	`/opt/moe-infra/agent-logs`	`/app/logs`	Orchestrator-Logs
`langgraph-orchestrator`	`/opt/moe-infra/chroma-onnx-cache`	`/root/.cache/chroma`	ChromaDB ONNX-Modell-Cache
`moe-admin`	`/opt/moe-infra/admin-logs`	`/app/logs`	Admin-UI-Logs
`moe-prometheus`	`/opt/moe-infra/prometheus-data`	`/prometheus`	Prometheus TSDB
`moe-grafana`	`/opt/grafana/data`	`/var/lib/grafana`	Grafana Daten
`moe-grafana`	`/opt/grafana/dashboards`	`/var/lib/grafana/dashboards`	Grafana Dashboards

Konfigurationsfiles (Read-Only-Mounts)¶

Service	Host-Pfad	Container-Pfad
`langgraph-orchestrator`	`/opt/deployment/moe-sovereign/moe-infra/.env`	`/app/.env` (ro)
`moe-admin`	`/opt/deployment/moe-sovereign/moe-infra/.env`	`/app/.env` (rw)
`moe-prometheus`	`./prometheus/prometheus.yml`	`/etc/prometheus/prometheus.yml` (ro)
`moe-grafana`	`./grafana/provisioning`	`/etc/grafana/provisioning` (ro)

Gemeinsame Volumes (Docker Named Volumes)¶

Volume	Gemountet in	Pfad
`userdb_data`	`langgraph-orchestrator`	`/app/userdb`
`userdb_data`	`moe-admin`	`/app/userdb`

Das userdb_data-Volume ist ein bind-mount auf /opt/moe-infra/userdb und wird von Orchestrator und Admin-UI gemeinsam genutzt (SQLite User-Datenbank).

Skills-Verzeichnis¶

Service	Host-Pfad	Container-Pfad	Modus
`langgraph-orchestrator`	`/home/philipp/.claude/commands`	`/app/skills`	ro
`moe-admin`	`/home/philipp/.claude/commands`	`/app/skills`	rw
`moe-admin`	`./skills-upstream`	`/app/skills-upstream`	rw

Start- und Stopp-Kommandos¶

Alle Services¶

# Starten
sudo docker compose up -d

# Stoppen (Container werden nicht gelöscht)
sudo docker compose down

# Stoppen und Volumes entfernen (Datenverlust!)
sudo docker compose down -v

# Status aller Services
sudo docker compose ps

Einzelne Services neu bauen¶

# Orchestrator neu bauen und starten
sudo docker compose build langgraph-app
sudo docker compose up -d langgraph-app

# MCP-Server neu bauen und starten
sudo docker compose build mcp-precision
sudo docker compose up -d mcp-precision

# Admin-UI neu bauen und starten
sudo docker compose build moe-admin
sudo docker compose up -d moe-admin

# Alle selbst gebauten Services neu bauen
sudo docker compose build langgraph-app mcp-precision moe-admin
sudo docker compose up -d langgraph-app mcp-precision moe-admin

Erststart (neue Umgebung)¶

# Verzeichnisse anlegen
sudo mkdir -p /opt/moe-infra/{neo4j-data,neo4j-logs,redis-data,chroma-data,chroma-onnx-cache,kafka-data,agent-logs,admin-logs,userdb,prometheus-data}
sudo mkdir -p /opt/grafana/{data,dashboards}

# .env aus Vorlage erstellen und anpassen
cp /opt/deployment/moe-sovereign/moe-infra/temp.env /opt/deployment/moe-sovereign/moe-infra/.env
# → URL_RTX, SEARXNG_URL, EXPERT_MODELS, GF_SECURITY_ADMIN_PASSWORD eintragen

# Alle Services bauen und starten
cd /opt/deployment/moe-sovereign/moe-infra
sudo docker compose up -d --build

Nützliche Docker-Kommandos für den Betrieb¶

Logs¶

# Live-Logs eines Services
sudo docker compose logs -f langgraph-orchestrator
sudo docker compose logs -f moe-admin
sudo docker compose logs -f moe-kafka

# Letzte 100 Zeilen
sudo docker logs langgraph-orchestrator --tail=100
sudo docker logs moe-admin --tail=50

# Kafka-spezifische Logs aus dem Orchestrator
sudo docker logs langgraph-orchestrator 2>&1 | grep -i kafka

Health-Checks¶

# Orchestrator API
curl http://localhost:8002/v1/models

# GraphRAG-Status
curl http://localhost:8002/graph/stats

# MCP-Server
curl http://localhost:8003/health

# Redis
sudo docker exec terra_cache redis-cli ping

# Kafka Topics
sudo docker exec moe-kafka kafka-topics \
  --bootstrap-server localhost:9092 --list

# Neo4j Browser
# → http://localhost:7474  (user: neo4j, pass: moe-sovereign)

# Prometheus
# → http://localhost:9090

# Grafana
# → http://localhost:3001

Ressourcen¶

# Container-Ressourcenverbrauch (live)
sudo docker stats

# Disk-Nutzung der Volumes
du -sh /opt/moe-infra/*/
du -sh /opt/grafana/*/

Troubleshooting¶

# Container-Details anzeigen
sudo docker inspect langgraph-orchestrator

# Shell in Container öffnen
sudo docker exec -it langgraph-orchestrator bash
sudo docker exec -it terra_cache redis-cli

# Netzwerk prüfen
sudo docker network ls
sudo docker network inspect moe-sovereign_default