Deployment

Wie eine Brain-Instanz aufgesetzt wird — Business zentral auf maniak-ähnlichem Server, Personal lokal auf Mac/VPS.

Stand: Plan-Level. Konkrete Befehle, Dockerfiles und Setup-Skripte kommen in Phase 6. Diese Datei fixiert die Architektur des Deployments.

1. Business Brain (auf 46.225.238.83 / ground.kuble.com)

Voraussetzungen (bereits erfüllt, Stand 2026-04-17)

  • Ubuntu 24.04 LTS auf dem Server
  • Docker 29+, docker-compose-plugin
  • Node 22+ (nicht auf dem Host nötig, läuft in Container — aber praktisch für Admin-CLI)
  • ground.kuble.com DNS → Server-IP
  • SSH-Zugang als root (perspektivisch: SSH-Keys, kein Passwort-Login)
  • Server sauber (siehe Wipe-Log in Memory kuble-servers.md)

Topologie auf dem Host

/opt/gts/                              ← Code + data root
├── compose.yaml                       ← docker compose
├── .env                               ← secrets (NEVER committed)
├── traefik/
│   ├── dynamic.yaml
│   └── acme.json                      ← Let's Encrypt storage
├── data/                              ← volumes, persistent
│   ├── brains/                        ← git-Repo (Source of Truth)
│   │   ├── .git/
│   │   ├── brains/slow/
│   │   ├── brains/rapid/
│   │   └── .gts/
│   │       ├── meta.sqlite
│   │       └── config.yaml
│   └── backups/                       ← periodic git bundle + sqlite dump
└── logs/

Docker-Komponenten

Service Image Port (intern) Domain
gts-traefik traefik:3.x 80, 443 public — (Proxy)
gts-server gts/server:<version> 3000 internal ground.kuble.com
gts-mcp gts/mcp:<version> 4000 internal (nicht öffentlich, via Agent-Tunnel oder Same-Host)

Alle Container im Docker-Netz gts-internal. Kein Overlap mit anderen Stacks (eigenes Netzwerk, eigenes Traefik — nicht das alte Nori-Traefik).

Einmaliges Setup (Phase 6 als Skript)

# 1. Code deployen
git clone <tooling-codebase-remote> /opt/gts-code
cd /opt/gts-code
npm install --omit=dev
npm run build

# 2. Instance initialisieren
./packages/cli/dist/cli.js init \
  --type business \
  --identity kuble \
  --data-dir /opt/gts/data

# 3. Secrets setzen
vi /opt/gts/.env     # AUTH_SECRET, GOOGLE_CLIENT_SECRET, DB-URL, etc.

# 4. Traefik + App starten
cd /opt/gts
docker compose up -d

# 5. Ersten Admin bootstrappen
docker compose exec gts-server gts admin bootstrap --email gustavo.salami@kuble.com
# → Setzt initiales Passwort, anschließend per UI ändern

Updates

cd /opt/gts-code
git pull
npm install --omit=dev
npm run build
# Image rebuilden / oder Live-Volume-Mount wenn dev
docker compose restart gts-server

Brain-Daten bleiben unberührt (Volume).

Backup

  • cron auf dem Host: nightly git bundle create /opt/gts/data/backups/brains-$(date +%F).bundle --all + sqlite3 /opt/gts/data/brains/.gts/meta.sqlite ".backup /opt/gts/data/backups/meta-$(date +%F).db".
  • Optional: zusätzlich git-remote push zu einem zweiten Host (z.B. privates GitHub-Repo oder selbst-gehosteter Gitea auf anderem Server).
  • Recovery-Pfad: git clone <bundle>, sqlite3 restore, docker compose up.

2. Personal Brain auf macOS (Gustavo's Mac Mini)

Voraussetzungen

  • macOS 14+ (aktuelle Versionen haben Apple Silicon Docker gut)
  • Docker Desktop oder direktes Node (Option A vs. Option B unten)
  • FileVault aktiviert (Disk-Encryption → at-rest Sicherheit für Private Soul)
  • Homebrew für optionale Tools

Option A — Docker (uniform mit Server)

  • Einfacher zu reasonen, gleicher Code-Pfad wie Business.
  • Braucht laufenden Docker-Desktop — ggf. nerv auf älteren Macs.

Option B — Native Node (leichter, empfohlen für Mac Mini)

  • npm install -g @gts/cli (aus published package, kommt Phase 3+).
  • gts init --type personal --identity gustavo --data-dir ~/.gts/gustavo.
  • Launchd-Plist auto-start:
    • ~/Library/LaunchAgents/com.kuble.gts-personal.plist
    • Startet gts serve --port 3100 beim Login.
  • UI erreichbar: http://localhost:3100.

Default: Option B für Menschen (schlankerer Footprint, keine Docker-Desktop-Abhängigkeit).

Verbindung zum Business (Web-UI oder CLI)

gts connect https://ground.kuble.com KBL-7A3X

Oder in der Personal-UI: "Verbundene Businesses → Neu" → URL + Code eingeben.

Ab hier läuft Selective Sync, wie in CONNECTIONS.md beschrieben.

3. Personal Brain auf einem Agent-Server (Maniak auf Hermes-VPS)

Für Agents ist es anders:

  • Kein Web-UI nötig (aber verfügbar). Agent greift direkt über die CLI oder MCP auf seine Personal-Instanz zu.
  • Key-only Login — das lokale Web-UI ist hinter Firewall/Tunnel, Agent nutzt einen API-Key via .env.
  • Deployment identisch zu Option B (Native Node), nur ohne Login-Flow. gts init --type personal --identity maniak --agent-mode.

Agents auf demselben Host wie der Business-Brain (z.B. Maniak-Agent auf Maniak-Server): gleiche Pattern, aber eigene Instanz-Directory. Keine Sonderfälle.

4. Checkliste pro Deploy

  • Disk-Encryption aktiviert auf dem Host
  • Regelmäßiger Backup-Job läuft
  • .env-Secrets sicher verwahrt (Password-Manager), nicht committed
  • Initialer Admin erzeugt, Passwort geändert
  • Zweiter Admin eingeladen (oder mindestens Recovery-Kontakt dokumentiert)
  • Firewall: nur SSH + 443 (Server) / SSH + lokaler Port (Mac/VPS) offen
  • DNS-Record lebt, TLS-Cert ausgestellt
  • Einmal gts validate laufen lassen — muss durchgehen
  • Einmal gts history laufen lassen — zeigt mindestens den initialen Commit