Écrire Compose toi-même

Cette page est ce qu’une stack doit reproduire quand tu écris Compose ou Kubernetes toi-même au lieu de lancer tale deploy : quels services tiennent l’état, les noms DNS, les sondes, les volumes. Le chemin CLI reste dans Démarrage rapide et Montées de version.

Quand ce chemin est le bon

Prends la CLI quand tu peux la faire tourner. Prends cette page quand tu écris Compose, ou quand tu maps le même contrat sur Kubernetes.

Il n’existe pas de chart Helm officiel.

Avec état et sans état

Dix services, deux sortes. Les services avec état tiennent les disques et l’identité fixe — tu les recrées, tu perds des données ou le DNS casse. Les services sans état sont des replicas interchangeables d’une image ; tu les recrées sur place à l’upgrade. Un seul fichier compose est le défaut. Des fichiers séparés ou Kubernetes t’appartiennent, tant que les noms DNS, le réseau sandbox isolé et l’ordre de démarrage restent.

sandbox-llm-gateway est le chemin harness : l’api le provisionne, et un conteneur de session l’atteint sous llm-gateway. bgutil-provider est le sidecar PO-token YouTube du worker, en best-effort — l’ingest de liens vidéo se dégrade sans lui.

Les trois services sans état partagent une image (ghcr.io/tale-project/tale/tale-platform:<version>). TALE_ROLE choisit api ou worker au boot ; l’étage web est la même image sans ce rôle. Épingle chaque image tale-* sur le même tag de release pour que les contrats de wire ne dérivent pas.

Les images

Chaque image tale-* est publiée sur la GitHub Container Registry sous le même tag de release, un seul numéro de version épingle donc toute la stack. Deux services tournent sur des images upstream qui ont leurs propres versions.

Une image n’est pas un service compose : le spawner crée chaque conteneur de session depuis ghcr.io/tale-project/tale/tale-sandbox-runtime:<version>, et son défaut intégré est le tag local que construit la stack de développement — un hôte qui ne l’a jamais construit nomme l’image de la registry dans SANDBOX_RUNTIME_IMAGE, sinon Run code, le rendu web et la génération de documents échouent tous sur une image introuvable. Les exemples ci-dessous épinglent la release que documente cette page ; remplace le tag par la release que tu installes.

Les services sans état

Le fichier ci-dessous, ce sont les trois rôles sans état — alias, /ping en liveness, TALE_ROLE, NET_ADMIN. Pose les services avec état dans le même fichier ou ailleurs ; les tableaux de cette page disent ce qu’ils doivent encore faire. Épingle le tag d’image et remplis .env depuis la Référence d’environnement.

# 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

Il n’existe pas de compose de production versionné à recopier. La CLI génère une paire de fichiers et l’efface après up. Ton fichier n’a pas à lui ressembler.

Les secrets que tu génères avant le premier boot

tale init génère chaque secret et écrit le .env ; sans la CLI, ce travail est le tien. La Référence d’environnement dit ce que fait chaque variable — les quatre ci-dessous sont celles qu’une stack montée à la main oublie le plus souvent, parce que le fichier d’exemple les laisse commentées pour que la CLI les remplisse.

L’endpoint public se pose avant de démarrer, pas après. Le backend seede la connexion blob par défaut du déploiement dans le volume de config au premier boot (default/object-storage/connection.json) et ne réécrit jamais un défaut déjà présent — poser la variable sur une instance déjà démarrée ne change donc rien. Pour réparer une instance dans cet état, ajoute "publicEndpoint": "<ton SITE_URL>" dans ce fichier et redémarre le backend.

Réseaux et noms DNS

Deux réseaux Docker portent chaque saut. Un réseau compose ordinaire suffit pour le plan interne. Le pont sandbox doit s’appeler tale-sandbox-net et être internal pour que le spawner puisse docker run --network tale-sandbox-net et qu’un conteneur de session ne joigne pas Internet sans passer par sandbox-egress. Un pont sans internal est un chemin ouvert vers l’extérieur.

Les workers n’ont pas d’alias partagé. Rien n’adresse un worker par nom ; ils ne font que prendre des jobs dans la queue. Les alias suffixés par une couleur (backend-api-blue, platform-green) ne servent que pour un blue-green pendant que deux versions tournent à la fois.

Le proxy envoie les voies API app vers backend-api:3005 (BACKEND_UPSTREAM). Il envoie /api/health et la SPA vers platform:3000, et il sonde platform sur /api/health. Fais échouer cette sonde sur une replica web en drain et Caddy marque tout le site down.

Volumes

Nomme ces volumes logiques dans ton compose. Un seul fichier peut laisser compose les créer. Marque-les external seulement si quelque chose hors de ce fichier doit monter les mêmes disques.

Les instances montées depuis avant 0.5.11 peuvent encore avoir un volume convex-data à côté de config-data. La CLI copie le magasin une fois et ne supprime jamais l’ancien volume. Un premier boot écrit à la main sur un hôte neuf n’a pas besoin de convex-data.

Sondes de santé

Liveness et readiness sont deux questions différentes. Les mélanger coupe une replica en drain du DNS avant la fin du travail en vol, ou garde une replica pas prête dans le pool.

Env que Compose doit injecter

La Référence d’environnement est chaque variable que le processus lit depuis .env. Les lignes ci-dessous sont ce que le fichier compose doit poser lui-même — les défauts de l’image pointent le processus vers le mauvais hôte.

Capacités et mounts qui cassent s’ils manquent

Ils ont l’air optionnels et échouent fermés quand ils manquent.

Ne publie que 80 et 443 sur proxy. Tout le reste reste sur le réseau interne.

Ordre de démarrage

Monte les stores d’abord, puis le plan sandbox, puis l’étage app. Une api qui démarre avant que db et object-store soient sains crash-loop sur ENOTFOUND et sur une base manquante. Dans un seul fichier, depends_on avec service_healthy suffit.

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.

Donne à chaque service une politique de redémarrage (restart: unless-stopped). Rien d’autre ne ramène un conteneur après un reboot de l’hôte ou un kill OOM, et une stack qui boote une fois et plus jamais est la panne que les opérateurs trouvent des semaines plus tard.

Les migrations de schéma tournent dans le backend au boot, sous un verrou advisory. Il n’y a pas d’étape migrate à part. Une replica qui ne peut pas appliquer une migration ne démarre pas ; laisse l’ancienne api tourner jusqu’à ce que la nouvelle soit saine.

Kubernetes

Pas de chart Helm, pas de manifeste officiel. Mappe le contrat Docker ; n’invente pas une seconde architecture.

Ne publie que 80 et 443. Laisse Postgres, MinIO et le port sandbox hors de la liste de Services publics.

Recréer sur place les Deployments sans état est le défaut. Le zéro downtime, c’est un rolling update que tu construis.

Ce que tu perds sans la CLI

tale deploy n’est pas un compose up. Les commandes ci-dessous n’ont pas d’équivalent dans un fichier que tu maintiens.

Recréer sur place les services sans état est le défaut. Le zéro downtime est la partie que tu réimplémentes.

Ce que la production ne doit pas faire

Ça a l’air local et casse une instance publique.

Où cela s’inscrit

Tu as maintenant le contrat : quels services tiennent l’état, deux réseaux, les noms DNS que le proxy et le sandbox résolvent, les sondes à ne pas inverser, et ce que Kubernetes doit encore faire. La Référence d’environnement est chaque variable que les conteneurs lisent. Architecture des conteneurs est ce que chaque conteneur possède quand l’un d’eux meurt. La plupart des équipes veulent encore le démarrage rapide et tale deploy — cette page est le chemin quand ce wrapper est précisément ce que tu ne peux pas faire tourner.