🚫 Le conteneur ne démarre pas

Vérifiez que les variables d'environnement obligatoires sont définies :

BETTER_AUTH_SECRET -- secret de signature des sessions
CONNECTION_ENCRYPTION_KEY -- clé de chiffrement des credentials (32 octets, base64)

Sans ces deux variables, le serveur refuse de démarrer. Générez-les avec :

openssl rand -base64 32

🗄️ Connexion à la base de données refusée

Vérifiez que DATABASE_URL pointe vers une instance PostgreSQL accessible
Assurez-vous que PostgreSQL est bien démarré : docker compose ps
Testez la connexion manuellement : psql $DATABASE_URL
Si vous n'avez pas défini DATABASE_URL, Appstrate utilise PGlite (Tier 0) -- aucune base externe n'est nécessaire

🤖 Les agents échouent à l'exécution

Vérifiez que RUN_ADAPTER=docker est défini pour l'exécution en conteneur
Vérifiez les permissions du socket Docker : le conteneur Appstrate doit avoir accès à /var/run/docker.sock
Assurez-vous que les images sont disponibles localement : docker images | grep appstrate
Si les images manquent, construisez-les ou récupérez-les depuis le registre

🔑 Le callback OAuth échoue

Vérifiez que APP_URL correspond exactement à votre URL publique, incluant le protocole et le port si nécessaire :

# Correct
APP_URL=https://appstrate.example.com

# Incorrect -- protocole manquant ou port manquant
APP_URL=appstrate.example.com
APP_URL=http://appstrate.example.com:3000  # si le reverse proxy écoute sur 443

L'URL configurée dans votre provider OAuth (Google, GitHub) doit correspondre à APP_URL.

🔴 Problèmes de connexion Redis

Vérifiez que REDIS_URL est correcte et que Redis est accessible
Sans Redis, le scheduling (cron) ne fonctionne pas -- les runs manuels restent opérationnels
Les fallbacks en mémoire (EventEmitter, Map) prennent le relais automatiquement, mais ne sont pas distribués

🔧 Erreurs du pool de sidecars

Si vous observez des erreurs liées au pool de sidecars, désactivez le pré-chauffage :

SIDECAR_POOL_SIZE=0

Cela désactive le pool de conteneurs sidecar pré-chauffés. Les sidecars seront créés à la demande pour chaque run.

📝 Activer les logs détaillés

Pour obtenir plus d'informations sur un problème, passez en mode debug :

LOG_LEVEL=debug

Redémarrez le conteneur après avoir modifié la variable. Les logs incluront les détails des imports dynamiques d'infrastructure, des connexions aux services, et de l'exécution des agents.

Appstrate nettoie automatiquement les conteneurs orphelins au démarrage. Les conteneurs gérés par la plateforme portent le label appstrate.managed=true. Si vous constatez des conteneurs résiduels, redémarrez Appstrate ou nettoyez-les manuellement :

docker ps -a --filter "label=appstrate.managed=true" -q | xargs docker rm -f

Dépannage