Déploiement en production

​

Prérequis

• Un serveur Linux avec Docker Engine 24.0+.
• Au moins 8 Go de RAM (12 Go recommandés pour les déploiements zero-downtime).
• Les ports 80 et 443 ouverts dans le firewall.
• Un nom de domaine qui pointe vers ton serveur.

​

Tailles des images

Astuce : Le premier pull télécharge ~4,4 Go (compressés). Les mises à jour suivantes ne téléchargent que les layers modifiés.

​

Installer le CLI Tale

curl -fsSL https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.sh | bash

curl -fsSL https://github.com/tale-project/tale/releases/latest/download/tale_linux \
  -o /usr/local/bin/tale
chmod +x /usr/local/bin/tale

​

Installation initiale

​

Étape 1 : initialiser le répertoire

mkdir ~/tale && cd ~/tale
tale init

​

Étape 2 : configurer l’environnement

HOST=yourdomain.com
SITE_URL=https://yourdomain.com
TLS_MODE=letsencrypt
TLS_EMAIL=admin@yourdomain.com
DB_PASSWORD=a-strong-database-password

​

Étape 3 : déployer

tale deploy

​

Gérer les déploiements

​

Déployer une nouvelle version

tale deploy                # déployer la version courante du CLI
tale deploy --dry-run      # prévisualiser sans déployer
tale deploy --all          # mettre aussi à jour DB et proxy

​

Statut

tale status

​

Logs

tale logs platform
tale logs platform --follow
tale logs db --tail 100

​

Rollback

tale rollback                      # revenir à la précédente
tale rollback --version 0.9.0      # revenir à une version précise

Changements de schéma forward-only. tale rollback n’échange que les images ; il ne rollback pas les données Convex. Voir Compatibilité de schéma et rollback.

​

Nettoyage

tale cleanup              # retirer les conteneurs inactifs
tale reset --force        # retirer TOUS les conteneurs (demande confirmation)

​

Zero-downtime

1. les nouveaux conteneurs démarrent à côté des actuels ;
2. les health checks confirment que la nouvelle version est prête ;
3. le trafic bascule ;
4. les anciens conteneurs sont drainés et retirés.

​

Configuration TLS

​

Let’s Encrypt (recommandé)

TLS_MODE=letsencrypt
TLS_EMAIL=admin@yourdomain.com

​

Auto-signé (dev)

TLS_MODE=selfsigned

docker exec tale-proxy caddy trust

​

TLS externe (derrière un reverse proxy)

TLS_MODE=external

​

Derrière un reverse proxy

HOST=yourdomain.com
SITE_URL=https://yourdomain.com
TLS_MODE=external

• terminer TLS et transférer tout le trafic (WebSocket compris) à Tale sur le port 80 ;
• poser les headers X-Forwarded-Proto et X-Forwarded-For.

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 443 ssl;
    server_name yourdomain.com;

    # ... ta config de certificat TLS ...

    location / {
        proxy_pass http://tale-server:80;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # support WebSocket
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        # timeouts longs pour la sync WebSocket Convex
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;

        proxy_buffering off;
    }
}

​

Déploiement en sous-chemin

HOST=yourdomain.com
SITE_URL=https://yourdomain.com
TLS_MODE=external
BASE_PATH=/tale

location /tale/ {
    proxy_pass http://tale-server:80;
    # ... mêmes headers et config WebSocket que plus haut ...
}

• Le Convex Dashboard (/convex-dashboard) n’est pas accessible en déploiement sous-chemin.

​

Utiliser une base externe

​

Exigences

​

Configuration

POSTGRES_URL=postgresql://tale:your-password@your-db-host:5432

RAG_DATABASE_URL=postgresql://tale:your-password@your-db-host:5432/tale_knowledge
CRAWLER_DATABASE_URL=postgresql://tale:your-password@your-db-host:5432/tale_knowledge

​

Initialisation DB

for f in services/db/init-scripts/*.sql; do
  psql -h your-db-host -U postgres -f "$f"
done

# Avec dbmate installé localement :
dbmate -u "postgresql://tale:your-password@your-db-host:5432/tale_knowledge" -d services/db/migrations/db/migrations up

# Ou via Docker (aucune installation locale nécessaire) :
docker run --rm -v "$PWD/services/db/migrations/db/migrations:/db/migrations" \
  amacneil/dbmate \
  -u "postgresql://tale:your-password@your-db-host:5432/tale_knowledge" up

​

Désactiver le conteneur DB fourni

services:
  db:
    profiles: ['disabled']

​

Upgrade depuis pre-split-convex (pre-v0.2.34)

tale upgrade                          # récupérer CLI + images
tale deploy --yes                     # non-interactif : appliquer migrations auto
                                      # (ou `tale deploy` pour confirmation interactive)
tale status                           # vérifier le nouveau setup

1. Détection — cherche ${projectId}_platform-data (prod) et/ou ${projectId}-dev_platform-data (dev) avec des données, et confirme que convex-data est vide ou absent.
2. Plan — affiche source/destination et quels conteneurs seront arrêtés. En interactif, le runner demande confirmation (défaut : Non) ; non-interactif exige --yes.
3. Arrêt — descend les projets compose/conteneurs tenant le volume source pour que cp -a n’entre pas en course avec un writer vivant.
4. Copie — docker run --rm --user 1001:1001 -v src:/src:ro -v dst:/dst alpine sh -c "cp -a /src/. /dst/ && touch /dst/.tale-migration-complete".
5. Vérification — compare les compteurs de fichiers entre source et destination.
6. Enregistrement — append l’ID de migration dans .tale/migrations.json pour que les runs suivants sautent. Le volume legacy est préservé pour permettre un downgrade.

​

Notes de sécurité

• La migration ne supprime pas ni ne modifie le volume legacy platform-data. Une fois le nouveau setup validé de bout en bout, libère l’espace :
  docker volume rm <projectId>_platform-data
  docker volume rm <projectId>-dev_platform-data   # si tu utilises le dev
  
• En cas de problème en pleine copie, relance tale deploy / tale start — la sentinelle .tale-migration-complete est vérifiée avant toute copie, et toute destination partielle est déplacée dans un volume de backup horodaté (…partial-<ts>) avant nouvelle tentative.
• Re-lancer après une migration réussie est un no-op.

​

Rollback d’un upgrade raté

tale rollback --version 0.2.33
# Ou downgrade le CLI :
curl -fsSL https://raw.githubusercontent.com/tale-project/tale/v0.2.x/scripts/install-cli.sh | bash
tale start

​

Compatibilité de schéma et rollback

​

Changements sûrs (rollback-friendly)

• Nouveaux champs optionnels dans tables existantes.
• Nouvelles tables.
• Nouveaux index.
• Nouvelles queries/mutations/actions.
• Retrait de champs que l’ancien code tolérait déjà comme optionnels.

​

Changements risqués (forward-only)

• Ajouter un champ requis à une table existante.
• Renommer un champ.
• Changer le type d’un champ.
• Retirer un champ requis sur lequel le nouveau code compte.
• Restructurer des documents dénormalisés.

​

Pattern recommandé : expand-contract

1. Expand — introduire la nouvelle forme à côté de l’ancienne. Code qui gère les deux formes. Migrer les données existantes via un backfill one-shot. Rollback sûr, car les deux formes marchent.
2. Contract — une fois que l’expand est stable en production, un release suit qui retire l’ancienne forme. Forward-only, mais les données sont garanties dans la nouvelle forme.

​

Fenêtre transitoire blue-green

1. green platform démarre et pousse V2 des functions.
2. Convex sert désormais V2 à tous — y compris les sessions ouvertes sur blue.
3. Le health check de Caddy voit green sain et bascule le trafic ; blue draine.
4. Les clients navigateur se reconnectent et prennent le nouveau code.

​

Scan de vulnérabilités

bun run docker:test:vulnerability

​

Versioning des images

• Tag de version (ex. 1.2.0) — immutable, pointe vers un build précis.
• latest — mutable, pointe toujours vers la release la plus récente.

# Pull d'une version précise
docker pull ghcr.io/tale-project/tale/tale-platform:1.2.0

# Pull de la dernière release
docker pull ghcr.io/tale-project/tale/tale-platform:latest

​

Accès au Convex Dashboard

1. Générer une clé admin :

./scripts/get-admin-key.sh

2. Copier la clé depuis la sortie.
3. Ouvrir https://yourdomain.com/convex-dashboard dans le navigateur.
4. Coller la clé admin quand elle est demandée.

Note : Le Convex Dashboard donne un accès direct en lecture et écriture à toutes les données. Ne partage des clés admin qu’avec des équipiers de confiance.