Compose selbst fahren

Diese Seite ist, was ein Stack reproduzieren muss, wenn du Compose oder Kubernetes selbst schreibst statt tale deploy zu laufen: welche Services Zustand halten, die DNS-Namen, die Probes, die Volumes. Der CLI-Weg bleibt in Quickstart und Upgrades.

Wann dieser Weg der richtige ist

Nimm die CLI, wenn du sie fahren kannst. Nimm diese Seite, wenn du Compose schreibst, oder wenn du denselben Vertrag auf Kubernetes abbildest.

Es gibt kein offizielles Helm-Chart.

Mit Zustand und ohne

Zehn Services, zwei Arten. Wer Zustand hält, trägt Platten und feste Identität — erzeugst du sie neu, verlierst du Daten oder bricht DNS. Zustandslose Services sind austauschbare Replicas eines Images; die erzeugst du beim Upgrade in place neu. Eine Compose-Datei ist der Default. Getrennte Dateien oder Kubernetes gehören dir, solange die DNS-Namen, das isolierte Sandbox-Netz und die Boot-Reihenfolge bleiben.

sandbox-llm-gateway ist der Harness-Pfad: die API provisioniert ihn, und ein Session-Container erreicht ihn als llm-gateway. bgutil-provider ist der YouTube-PO-Token-Sidecar des Workers und best-effort — Video-Link-Ingest fällt ohne ihn zurück.

Die drei zustandslosen Services teilen sich ein Image (ghcr.io/tale-project/tale/tale-platform:<version>). TALE_ROLE wählt beim Boot api oder worker; der Web-Tier ist dasselbe Image ohne diese Rolle. Pinne jedes tale-*-Image auf denselben Release-Tag, damit die Wire-Contracts nicht auseinanderlaufen.

Die Images

Jedes tale-*-Image liegt in der GitHub Container Registry unter demselben Release-Tag, eine Versionsnummer pinnt also den ganzen Stack. Zwei Services fahren Upstream-Images mit eigenen Versionen.

Ein Image ist kein Compose-Service: Der Spawner erzeugt jeden Session-Container aus ghcr.io/tale-project/tale/tale-sandbox-runtime:<version>, und sein eingebauter Default ist der lokale Tag, den der Entwicklungs-Stack baut — ein Host, der ihn nie gebaut hat, nennt das Registry-Image in SANDBOX_RUNTIME_IMAGE, sonst scheitern Run code, Web-Rendering und Dokumentgenerierung an einem fehlenden Image. Die Beispiele unten pinnen den Release, den diese Seite dokumentiert; ersetz den Tag durch den Release, den du installierst.

Die zustandslosen Services

Unten stehen die drei zustandslosen Rollen — Aliase, /ping als Liveness, TALE_ROLE, NET_ADMIN. Leg die Services mit Zustand in dieselbe Datei oder woanders hin; die Tabellen auf dieser Seite sagen, was sie trotzdem tun müssen. Pinne den Image-Tag und füll .env aus der Umgebungsreferenz.

# Stateless app tier. No container_name: --scale needs free names.
# Add db, proxy, sandbox, … in this file or another — your call. In one file,
# add depends_on: { db: { condition: service_healthy }, … } as well.
services:
  platform:
    image: ghcr.io/tale-project/tale/tale-platform:0.5.11
    env_file: [.env]
    volumes: ['config-data:/app/data:ro']
    restart: unless-stopped
    stop_grace_period: 45s
    healthcheck:
      test:
        [
          'CMD-SHELL',
          'curl -sf http://localhost:3000/api/health && [ -f /tmp/platform-ready ]',
        ]
      interval: 5s
      timeout: 3s
      retries: 3
      start_period: 180s
    networks:
      internal:
        aliases: [platform]
  backend-api:
    image: ghcr.io/tale-project/tale/tale-platform:0.5.11
    environment:
      TALE_ROLE: api
      PORT: '3005'
      TALE_CONFIG_DIR: /app/data
      DATABASE_URL: postgresql://tale:${DB_PASSWORD}@db:5432/tale_app
      SANDBOX_URL: http://sandbox:8003
      SANDBOX_HTTP_API_BASE_URL: http://backend-api:3005
      OBJECT_STORE_ENDPOINT: http://object-store:9000
    env_file: [.env]
    volumes: ['config-data:/app/data']
    cap_add: [NET_ADMIN]
    restart: unless-stopped
    healthcheck:
      test: ['CMD-SHELL', 'curl -sf http://localhost:3005/ping']
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 30s
    networks:
      internal:
        aliases: [backend-api]
      sandbox:
        aliases: [backend-api]
  backend-worker:
    image: ghcr.io/tale-project/tale/tale-platform:0.5.11
    environment:
      TALE_ROLE: worker
      TALE_CONFIG_DIR: /app/data
      DATABASE_URL: postgresql://tale:${DB_PASSWORD}@db:5432/tale_app
      SANDBOX_URL: http://sandbox:8003
      SANDBOX_HTTP_API_BASE_URL: http://backend-api:3005
      OBJECT_STORE_ENDPOINT: http://object-store:9000
    env_file: [.env]
    volumes: ['config-data:/app/data']
    cap_add: [NET_ADMIN]
    restart: unless-stopped
    healthcheck: { disable: true }
    networks: [internal]
volumes:
  config-data:
networks:
  internal:
  sandbox:
    name: tale-sandbox-net
    internal: true
    enable_ipv6: false

Es gibt kein eingechecktes Produktions-Compose zum Kopieren. Die CLI erzeugt ein geteiltes Dateipaar und löscht es nach up. Deine Datei muss nicht so aussehen.

Secrets, die du vor dem ersten Boot erzeugst

tale init erzeugt jedes Secret und schreibt die .env; ohne die CLI ist das dein Job. Die Umgebungsreferenz sagt, was jede Variable tut — die vier unten sind die, die ein selbst gebauter Stack am häufigsten vergisst, weil die Beispieldatei sie auskommentiert lässt, damit die CLI sie füllt.

Den Public-Endpoint bringst du vor dem Start in Ordnung, nicht danach. Das Backend seedet die Deployment-Default-Blob-Verbindung beim ersten Boot ins Config-Volume (default/object-storage/connection.json) und überschreibt einen bereits vorhandenen Default nie — die Variable auf einer schon gebooteten Instanz zu setzen, ändert also nichts. Zum Reparieren trägst du "publicEndpoint": "<deine SITE_URL>" in diese Datei ein und startest das Backend neu.

Netze und DNS-Namen

Zwei Docker-Netze tragen jeden Hop. Ein gewöhnliches Compose-Netz reicht für die interne Ebene. Die Sandbox-Bridge muss tale-sandbox-net heißen und internal sein, damit der Spawner docker run --network tale-sandbox-net kann und ein Session-Container das Internet nicht ohne sandbox-egress erreicht. Eine Bridge ohne internal ist ein offener Weg nach draußen.

Worker haben keinen geteilten Alias. Nichts adressiert einen Worker per Name; sie holen Jobs nur aus der Queue. Farb-suffigierte Aliase (backend-api-blue, platform-green) sind nur für ein Blue-Green, während zwei Versionen gleichzeitig oben sind.

Der Proxy schickt App-API-Lanes an backend-api:3005 (BACKEND_UPSTREAM). /api/health und die SPA gehen an platform:3000, und er prüft platform auf /api/health. Fällt diese Probe auf einer drainenden Web-Replica aus, markiert Caddy die ganze Site als down.

Volumes

Nenn diese logischen Volumes in deinem Compose. Eine Datei kann Compose sie anlegen lassen. Markier sie nur als external, wenn etwas außerhalb dieser Datei dieselben Disks mounten muss.

Instanzen, die vor 0.5.11 upgraded wurden, haben neben config-data oft noch ein convex-data-Volume. Die CLI kopiert den Store einmal rüber und löscht das alte Volume nie. Ein handgeschriebenes First-Boot auf einem frischen Host braucht convex-data nicht.

Health-Probes

Liveness und Readiness sind verschiedene Fragen. Wer sie vertauscht, schneidet eine drainende Replica aus dem DNS, bevor In-flight-Arbeit fertig ist — oder lässt eine unfertige Replica im Pool.

Env, die Compose setzen muss

Die Umgebungsreferenz ist jede Variable, die der Prozess aus .env liest. Die Zeilen darunter muss die Compose-Datei selbst setzen — Image-Defaults zeigen den Prozess auf den falschen Host.

Capabilities und Mounts, die ohne sie brechen

Die sehen optional aus und gehen geschlossen kaputt, wenn sie fehlen.

Veröffentliche nur 80 und 443 auf proxy. Alles andere bleibt im internen Netz.

Boot-Reihenfolge

Fahr die Stores zuerst hoch, dann die Sandbox-Ebene, dann den App-Tier. Eine API, die startet, bevor db und object-store healthy sind, crash-loopt auf ENOTFOUND und auf einer fehlenden Datenbank. In einer Datei reicht depends_on mit service_healthy.

docker compose up -d
# Wait until db, object-store, proxy, sandbox, sandbox-egress, sandbox-llm-gateway
# report healthy. bgutil-provider is best-effort — YouTube ingest degrades without it.

Gib jedem Service eine Restart-Policy (restart: unless-stopped). Nichts sonst holt einen Container nach einem Host-Reboot oder einem OOM-Kill zurück, und ein Stack, der einmal bootet und danach nie wieder, ist der Fehler, den Operatoren Wochen später finden.

Schema-Migrationen laufen im Backend beim Boot, unter einem Advisory-Lock. Es gibt keinen eigenen Migrate-Schritt. Eine Replica, die eine Migration nicht anwenden kann, startet nicht; lass die vorherige API laufen, bis die neue healthy ist.

Kubernetes

Es gibt kein Helm-Chart und kein offizielles Manifest. Map den Docker-Vertrag; erfinde keine zweite Architektur.

Veröffentliche nur 80 und 443. Lass Postgres, MinIO und den Sandbox-Port von der öffentlichen Service-Liste.

Ein In-place-Recreate der zustandslosen Deployments ist der Default. Zero-Downtime ist ein Rolling Update, den du selbst baust.

Was du ohne die CLI aufgibst

tale deploy ist kein Compose-Up. Die Kommandos darunter haben kein Äquivalent in einer Datei, die du pflegst.

Ein In-place-Recreate der zustandslosen Services ist der Default. Zero-Downtime ist der Teil, den du selbst nachbaust.

Was Produktion nicht tun darf

Die sehen lokal aus und zerlegen eine öffentliche Instanz.

Wo das hingehört

Du hast jetzt den Vertrag: welche Services Zustand halten, zwei Netze, die DNS-Namen, die Proxy und Sandbox auflösen, die Probes, die du nicht tauschen darfst, und was Kubernetes trotzdem tun muss. Die Umgebungsreferenz ist jede Variable, die die Container lesen. Container-Architektur ist, was jeder Container besitzt, wenn einer stirbt. Die meisten Teams wollen weiter den Quickstart und tale deploy — diese Seite ist der Weg, wenn genau dieser Wrapper das ist, was du nicht fahren kannst.