Zum Hauptinhalt springen

​
v0.2.34 — Convex in einen eigenen Dienst abspalten

​
TL;DR

Convex läuft jetzt als eigener Docker-Dienst (convex) statt eingebettet im platform-Container. Platform wird ein schlanker Vite/TanStack-Start-Client, der Schema und Env-Vars per HTTP an Convex pusht. Bestehende Deployments werden beim nächsten tale start / tale deploy nach tale upgrade automatisch migriert — es gibt kein separates tale migrate. 
# Dev:
tale upgrade
tale start              # erkennt offene Migrationen, fragt nach Bestätigung

# Produktion:
tale upgrade
tale deploy             # erkennt offene Migrationen, fragt nach Bestätigung
# Oder nicht-interaktiv (CI):
tale deploy --yes
Nutzer älter als v0.2.33 sehen zwei Migrationen in einem einzigen Schritt: erst namespace-volumes (Umbenennung tale_* → ${projectId}_*), dann split-convex (dieses Release). Beide sind idempotent und können erneut ausgeführt werden.

​
Warum

Das alte All-in-One-Layout koppelte den Vite-Frontend-Lebenszyklus an Convex. Ein langsamer convex push oder ein transienter Rust-Crash ließ den Platform-Healthcheck scheitern und zog die ganze Site aus dem Load-Balancer — auch wenn Vite selbst in Ordnung war. Jeder Convex-Backend-Bump erzwang einen vollen Platform-Rebuild, und Blue-Green-Deployments mussten zwei gleichwertige Platform-Container koordinieren, die sich um dasselbe Convex-Daten-Volume stritten. Das neue Layout behandelt Convex wie eine Datenbank — ein unabhängiger Dienst mit eigenem Image, eigenem Volume und eigenem Lebenszyklus. Code-Änderungen bauen nur das Platform-Image neu; der Convex-Container läuft weiter und WebSocket-Clients bleiben verbunden.

​
Was sich geändert hat

​
Architektur

  • Neuer convex-Dienst läuft convex-local-backend + Convex-Dashboard. Er hält das convex-data-Volume (aus platform-data migriert).
  • Neues tale-convex-Docker-Image (~485 MB komprimiert).
  • Platform-Image von ~2,58 GB auf ~320 MB komprimiert verschlankt — behält die generate_key-Binary aus dem convex-backend-Basis-Image (nötig zum Signieren von Admin-Tokens für den Remote-Push), aber ohne Backend-Daemon, Dashboard und Builtin-Seed-Assets.
  • Caddys Upstream-Pfade (/ws_api, /http_api, /api/storage, /convex-dashboard, /api/*/sync, …) werden von platform:* auf convex:* umgeroutet.
  • Die Dienste rag und crawler lesen ihre gemeinsame Anbieter-Konfiguration jetzt aus convex-data:/app/platform-config:ro statt aus platform-data.

​
Platform-Start (Push-Modell)

Der Platform-Entrypoint:
  1. wartet auf http://convex:3210/version (den Geschwister-Convex-Dienst);
  2. pusht 24 Env-Vars via bunx convex env set (Secrets, URLs, Datei-Pfad-Semantik);
  3. führt bunx convex deploy --url http://convex:3210 mit 300 s Default-Timeout aus;
  4. klassifiziert Deploy-Fehler in die Stufen start_push / wait_for_schema / finish_push mit zugeschnittener Diagnose;
  5. legt /tmp/platform-ready an — der Compose-Healthcheck-Gate, der Traffic bis zum erfolgreichen Deploy blockiert.
Env-Vars werden in Convex’ eigener Datenbank persistiert, sodass ein Convex-Neustart keinen erneuten Push erfordert.

​
Migrations-Framework

Das Migrations-Subsystem der CLI (eingeführt in v0.2.33) ist jetzt eine generische, version-agnostische Pipeline. Jede Migration ist ein Registrier-Eintrag mit detect-, requiredStops- und apply-Hooks; tale start und tale deploy errechnen zur Laufzeit den offenen Satz und fragen vor der Anwendung nach.
  • Kein neues nutzerseitiges Flag in diesem Release. Die Pipeline führt alles Offene in Registrier-Reihenfolge aus.
  • tale deploy --yes akzeptiert offene Migrationen nicht-interaktiv (ersetzt das veraltete --migrate-volumes, das noch als Alias funktioniert).
  • Persistierter Zustand liegt in .tale/migrations.json (nur-hinzufügendes applied[]); der Legacy-Marker .tale/migration-pending wird beim ersten Lauf automatisch migriert.

​
Dev-Workflow

  • Standard-bun run dev funktioniert weiter (startet bunx convex dev lokal auf 127.0.0.1:3210).
  • Neuer Modus CONVEX_EXTERNAL=true bun run dev für Vite gegen ein containerisiertes Convex (docker compose up convex).
  • vite.config.ts liest CONVEX_URL / CONVEX_SITE_PROXY_URL für Proxy-Ziele.

​
Upgrade-Anleitung

Wichtig: Die Migration erzeugt kein automatisches Backup deiner Daten — sie erhält das Legacy-Volume ${projectId}_platform-data an Ort und Stelle, nachdem sie seinen Inhalt in das neue ${projectId}_convex-data kopiert hat. Willst du vor dem Upgrade ein hartes Backup, snapshott das Volume selbst (z. B. docker run --rm -v ${projectId}_platform-data:/src:ro -v $(pwd):/out alpine tar -C /src -czf /out/platform-data-backup.tgz .). Es gibt kein separates tale migrate. Migrationen sind Teil des normalen Start-/Deploy-Flows: 
tale upgrade            # schreibt nichts Destruktives; zeigt, welche Migrationen offen sind
tale start              # Dev: erkennt offene Migrationen, fragt [y/N], dann Start
# oder in Produktion:
tale deploy             # erkennt offene Migrationen, fragt [y/N], dann Deploy
# Nicht-interaktiv (CI):
tale deploy --yes       # nimmt offene Migrationen ohne Nachfrage an
Der Migration-Runner:
  1. erkennt jede offene Migration im Register (aktuelles Set: split-convex, plus namespace-volumes für Nutzer pre-v0.2.33);
  2. druckt den Plan: welche Migrationen, welche Container kurz gestoppt werden, geschätzte Auswirkungen;
  3. fragt [y/N] (Default: Nein). Ablehnen → sauberer Exit mit Code 2; nichts geändert.
  4. Bei Bestätigung: stoppt betroffene Container, kopiert Daten mit cp -a --user 1001:1001, verifiziert strikte Datei-Zählung (src + 1 Sentinel == dst), protokolliert die Migration in .tale/migrations.json.
  5. Lässt das alte Volume unangetastet.
Sobald das neue Setup funktioniert, gibst du den Platz frei: 
docker volume rm <projectId>_platform-data
docker volume rm <projectId>-dev_platform-data   # falls du Dev-Mode genutzt hast

​
Inkompatible Änderungen

  • Der platform-Container mountet /app/data nicht mehr read-write. Wenn du eigene Bind-Mounts in platform-data hattest, schreibe sie auf convex-data um.
  • platform exponiert die Ports 3210, 3211, 6791 nicht mehr — die liegen jetzt auf convex. Caddys Routing übernimmt den Übergang transparent; nur eigene Test-Harnesses, die direkt auf die Ports gehen, brauchen ein Update.
  • platform-data:/app/platform-config:ro-Mounts auf rag / crawler werden zu convex-data:/app/platform-config:ro. Wenn du diese Dienste eigenständig mit handgeschriebenen Compose-Files betreibst, die Mount-Quelle anpassen.
  • Der Docker-Healthcheck des Platform-Containers prüft jetzt nur Vite (/api/health) — Convex muss nicht mehr gesund sein. Convex hat einen eigenen, unabhängigen Healthcheck.

​
Rollback

tale rollback --version 0.2.x funktioniert, solange platform-data erhalten ist. Das alte Image erwartet platform-data:/app/data, das die Migration nicht anfasst. Nach dem Rollback: 
# Optionales Cleanup: ungenutztes convex-data-Volume entfernen
docker volume rm <projectId>_convex-data
Siehe Produktions-Deployment → Schema-Kompatibilität und Rollback für den Umgang mit Schema-Änderungen über Versionen hinweg.

​
Bekannte Einschränkungen

  • Blue-Green-Übergangsfenster (~10–30 s): während des Cutovers bedient blue-Platform noch Nutzer, während green bereits neue Convex-Functions deployed hat. Entfernt oder benennt der neue Deploy eine Function, sehen Blue-Clients in diesem Fenster 404. Nutze Expand-Contract für Breaking Changes.
  • Nur-Vorwärts-Schema: tale rollback tauscht Container-Images, aber nicht Convex-Daten. Pflichtfeld-Erweiterungen, Umbenennungen und Typ-Änderungen folgen dem Zwei-Release-Expand-Contract-Muster aus Schema-Kompatibilität und Rollback.
  • Der erste Deploy nach der Migration dauert länger als die folgenden, weil die Convex-Env-Vars alle “neu” sind — rechne mit ~30–60 s für Env-Sync + Deploy-Abschluss beim ersten Boot.
Last modified on April 20, 2026