Zum Inhalt

Docker-Container-Leitfaden

Andere Sprachen

Symbi stellt einen einheitlichen Docker-Container mit allen Funktionen bereit, verfuegbar ueber die GitHub Container Registry.

Verfuegbares Image

Einheitlicher Symbi-Container

  • Image: ghcr.io/thirdkeyai/symbi:latest
  • Zweck: All-in-One-Container mit DSL-Parsing, Agenten-Laufzeit und MCP-Server
  • Groesse: ~80MB (inkl. Vektordatenbank und HTTP-API-Unterstuetzung)
  • CLI: Einheitlicher symbi-Befehl mit Unterbefehlen fuer verschiedene Operationen

Schnellstart

Projekt erstellen und starten (empfohlen)

symbi init funktioniert innerhalb des Containers und schreibt ein Projekt in Ihr Host-Verzeichnis, einschliesslich einer sofort lauffaehigen docker-compose.yml und einer .env mit einem frisch generierten SYMBIONT_MASTER_KEY:

# 1. Projektdateien auf dem Host erstellen
docker run --rm -v $(pwd):/workspace ghcr.io/thirdkeyai/symbi:latest \
  init --profile assistant --no-interact --dir /workspace

# 2. Runtime starten (liest .env automatisch)
docker compose up

Das Flag --dir /workspace weist symbi init an, in das gemountete Volume zu schreiben anstatt in das WORKDIR des Images. Nach der Ausfuehrung haben Sie symbiont.toml, agents/, policies/, .symbiont/audit/, AGENTS.md, docker-compose.yml, .env und .env.example im aktuellen Verzeichnis.

Um die Generierung der Compose-Datei zu ueberspringen:

docker run --rm -v $(pwd):/workspace ghcr.io/thirdkeyai/symbi:latest \
  init --profile minimal --no-interact --no-docker-compose --dir /workspace

Vorgefertigtes Image verwenden (ad-hoc)

# Neuestes Image herunterladen
docker pull ghcr.io/thirdkeyai/symbi:latest

# Eine Agentendefinition parsen (`.symbi`; das Legacy-Format `.dsl` wird ebenfalls akzeptiert)
docker run --rm -v $(pwd):/workspace \
  ghcr.io/thirdkeyai/symbi:latest \
  dsl --file /workspace/agent.symbi

# MCP-Server starten (stdio-basiert, kein Port erforderlich)
docker run --rm -i \
  ghcr.io/thirdkeyai/symbi:latest \
  mcp

# Runtime ohne Projekt starten (ephemer, kein Master Key)
docker run --rm -p 8080:8080 -p 8081:8081 \
  ghcr.io/thirdkeyai/symbi:latest \
  up --http-bind 0.0.0.0

Entwicklungs-Workflow

# Interaktive Entwicklung
docker run --rm -it -v $(pwd):/workspace \
  ghcr.io/thirdkeyai/symbi:latest bash

# Entwicklung mit Volume-Mounts und Ports
docker run --rm -it \
  -v $(pwd):/workspace \
  -p 8080:8080 \
  -p 8081:8081 \
  ghcr.io/thirdkeyai/symbi:latest bash

Verfuegbare Tags

  • latest - Neuestes stabiles Release
  • main - Neuester Entwicklungs-Build
  • v1.0.0 - Spezifische Versionsreleases
  • sha-<commit> - Spezifische Commit-Builds

Lokal bauen

Einheitlicher Symbi-Container

# Vom Projektstammverzeichnis
docker build -t symbi:latest .

# Build testen
docker run --rm symbi:latest --version

# DSL-Parsing testen
docker run --rm -v $(pwd):/workspace symbi:latest dsl --help

# MCP-Server testen
docker run --rm symbi:latest mcp

Multi-Architektur-Unterstuetzung

Images werden gebaut fuer: - linux/amd64 (x86_64) - linux/arm64 (ARM64/Apple Silicon)

Docker laedt automatisch die korrekte Architektur fuer Ihre Plattform herunter.

Sicherheitsfunktionen

Ausfuehrung als Nicht-Root

  • Container laufen als Nicht-Root-Benutzer symbi (UID 1000)
  • Minimale Angriffsflaeche mit sicherheitsgehaerteten Basis-Images

Schwachstellenscanning

  • Alle Images werden automatisch mit Trivy gescannt
  • Sicherheitshinweise werden im GitHub-Security-Tab veroeffentlicht
  • SARIF-Berichte fuer detaillierte Schwachstellenanalyse

Konfiguration

Umgebungsvariablen

Symbi-Container: - SYMBIONT_MASTER_KEY - Erforderlich fuer persistenten Zustand. 32-Byte-Hex-Schluessel zur Verschluesselung des lokalen Speichers. Generieren mit openssl rand -hex 32. symbi init schreibt automatisch einen in .env. - RUST_LOG - Logging-Level festlegen (debug, info, warn, error) - SYMBIONT_VECTOR_BACKEND - Vektor-Backend: lancedb (Standard) oder qdrant - QDRANT_URL - Qdrant-Vektordatenbank-URL (nur bei Verwendung des optionalen Qdrant-Backends) - OPENROUTER_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY - Optionale LLM-Zugangsdaten; schon eine davon aktiviert den Coordinator-Chat-Endpunkt.

Volume-Mounts

Das Image laeuft als Benutzer symbi (UID 1000) mit WORKDIR=/var/lib/symbi. Projektdateien werden schreibgeschuetzt in dieses Verzeichnis gemountet; persistente Zustaende (der lokale SQLite-Speicher und Audit-Logs) liegen in benannten Volumes, damit sie Container-Neustarts ueberdauern.

# Projektdateien (schreibgeschuetzt)
-v $(pwd)/symbiont.toml:/var/lib/symbi/symbiont.toml:ro
-v $(pwd)/agents:/var/lib/symbi/agents:ro
-v $(pwd)/policies:/var/lib/symbi/policies:ro
-v $(pwd)/tools:/var/lib/symbi/tools:ro

# Persistenter Zustand
-v symbi-data:/var/lib/symbi/.symbi
-v symbi-audit:/var/lib/symbi/.symbiont

Docker Compose Beispiel

symbi init erzeugt eine sofort lauffaehige docker-compose.yml, die mit dem Rest dieses Abschnitts uebereinstimmt — bevorzugen Sie das gegenueber einer handgeschriebenen Compose-Datei. Als Referenz oder wenn Sie ohne init starten:

Standardmaessig verwendet Symbiont LanceDB als eingebettete Vektordatenbank -- keine externen Dienste erforderlich. Wenn Sie ein verteiltes Vektor-Backend fuer skalierte Deployments benoetigen, koennen Sie optional Qdrant hinzufuegen.

Sicherheits-Standardwerte (nach dem v1.13.0-Audit). Die mitgelieferte docker-compose.test.yml setzt nun voraus, dass SYMBIONT_API_TOKEN in der Umgebung gesetzt ist (kein Standardwert mehr -- testtoken123 wurde entfernt) und bindet veroeffentlichte Ports an 127.0.0.1 statt 0.0.0.0. Die Runtime lehnt zusaetzlich jeden Token ab, der exakt testtoken123 lautet oder mit test beginnt und kuerzer als 20 Zeichen ist; dies verhindert das versehentliche erneute Deployment des historischen Standardwerts. Siehe .env.example fuer die erforderlichen Variablen und SECURITY_AUDIT.md C5 fuer die Begruendung.

Minimal (LanceDB-Standard -- kein Qdrant erforderlich)

Kombinieren Sie dies mit einer .env-Datei, die SYMBIONT_MASTER_KEY setzt:

services:
  symbi:
    image: ghcr.io/thirdkeyai/symbi:latest
    command: ["up", "--http-bind", "0.0.0.0"]
    ports:
      - "8080:8080"
      - "8081:8081"
    volumes:
      - ./symbiont.toml:/var/lib/symbi/symbiont.toml:ro
      - ./agents:/var/lib/symbi/agents:ro
      - ./policies:/var/lib/symbi/policies:ro
      - ./tools:/var/lib/symbi/tools:ro
      - symbi-data:/var/lib/symbi/.symbi
      - symbi-audit:/var/lib/symbi/.symbiont
    environment:
      SYMBIONT_MASTER_KEY: ${SYMBIONT_MASTER_KEY:?set SYMBIONT_MASTER_KEY in .env}
      RUST_LOG: ${RUST_LOG:-info}
    restart: unless-stopped

volumes:
  symbi-data:
  symbi-audit:

Mit optionalem Qdrant-Backend

services:
  symbi:
    image: ghcr.io/thirdkeyai/symbi:latest
    command: ["up", "--http-bind", "0.0.0.0"]
    ports:
      - "8080:8080"
      - "8081:8081"
    volumes:
      - ./symbiont.toml:/var/lib/symbi/symbiont.toml:ro
      - ./agents:/var/lib/symbi/agents:ro
      - ./policies:/var/lib/symbi/policies:ro
      - symbi-data:/var/lib/symbi/.symbi
      - symbi-audit:/var/lib/symbi/.symbiont
    environment:
      SYMBIONT_MASTER_KEY: ${SYMBIONT_MASTER_KEY:?set SYMBIONT_MASTER_KEY in .env}
      RUST_LOG: ${RUST_LOG:-info}
      SYMBIONT_VECTOR_BACKEND: qdrant
      QDRANT_URL: http://qdrant:6334
    depends_on:
      - qdrant
    restart: unless-stopped

  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - qdrant-data:/qdrant/storage

volumes:
  symbi-data:
  symbi-audit:
  qdrant-data:

Fehlerbehebung

Haeufige Probleme

Zugriff verweigert: 

# Korrektes Eigentum sicherstellen
sudo chown -R 1000:1000 ./data

# Oder anderen Benutzer verwenden
docker run --user $(id -u):$(id -g) ...

Port-Konflikte: 

# Andere Ports verwenden
docker run -p 8081:8080 ghcr.io/thirdkeyai/symbi:latest

Build-Fehler: 

# Docker-Cache leeren
docker builder prune -a

# Ohne Cache neu bauen
docker build --no-cache .

Gesundheitspruefungen

# Container-Gesundheit pruefen
docker run --name symbi-test -d ghcr.io/thirdkeyai/symbi:latest up --http-bind 0.0.0.0:8080
docker exec symbi-test /usr/local/bin/symbi --version
docker rm -f symbi-test

Performance-Optimierung

Ressourcenlimits

# Speicher- und CPU-Limits setzen
docker run --memory=512m --cpus=1.0 \
  ghcr.io/thirdkeyai/symbi:latest mcp

Build-Optimierung

# BuildKit fuer schnellere Builds verwenden
DOCKER_BUILDKIT=1 docker build .

# Multi-Stage-Caching
docker build --target builder -t symbi-builder .
docker build --cache-from symbi-builder .

CI/CD-Integration

GitHub Actions baut und veroeffentlicht Container automatisch bei: - Push auf den main-Branch - Neue Versions-Tags (v*) - Pull Requests (nur Build)

Images enthalten Metadaten: - Git-Commit-SHA - Build-Zeitstempel - Schwachstellen-Scan-Ergebnisse - SBOM (Software Bill of Materials)