xpeditis2.0/docs/deployment/PORTAINER_YAML_FIX.md

🔧 Fix Portainer YAML - Types de Variables d'Environnement

❌ Problème

Lors du déploiement sur Portainer, vous pouvez rencontrer cette erreur :

Deployment error
services.xpeditis-backend.environment.DATABASE_LOGGING must be a string, number or null

📝 Explication

Dans Docker Compose version 3.x (utilisé par Portainer), toutes les variables d'environnement doivent être des strings.

Les valeurs booléennes (true, false) et numériques sans guillemets (5432, 10, 0) ne sont PAS acceptées par Portainer, même si elles fonctionnent en local avec docker-compose.

Pourquoi ça fonctionne en local ?

Docker Compose CLI (utilisé en local) est plus permissif et convertit automatiquement les types. Portainer est plus strict et applique la spécification YAML à la lettre.

✅ Solution

Convertir toutes les valeurs non-string en strings avec des guillemets :

❌ Avant (ne fonctionne pas sur Portainer)

environment:
  PORT: 4000                    # ❌ Number
  DATABASE_PORT: 5432           # ❌ Number
  DATABASE_SYNC: false          # ❌ Boolean
  DATABASE_LOGGING: false       # ❌ Boolean
  REDIS_DB: 0                   # ❌ Number
  BCRYPT_ROUNDS: 10             # ❌ Number
  SESSION_TIMEOUT_MS: 7200000   # ❌ Number
  RATE_LIMIT_TTL: 60            # ❌ Number
  RATE_LIMIT_MAX: 100           # ❌ Number

✅ Après (fonctionne sur Portainer)

environment:
  PORT: "4000"                  # ✅ String
  DATABASE_PORT: "5432"         # ✅ String
  DATABASE_SYNC: "false"        # ✅ String
  DATABASE_LOGGING: "false"     # ✅ String
  REDIS_DB: "0"                 # ✅ String
  BCRYPT_ROUNDS: "10"           # ✅ String
  SESSION_TIMEOUT_MS: "7200000" # ✅ String
  RATE_LIMIT_TTL: "60"          # ✅ String
  RATE_LIMIT_MAX: "100"         # ✅ String

🔍 Variables Modifiées

Dans docker/portainer-stack.yml, les variables suivantes ont été converties en strings :

Variable	Avant	Après
PORT	4000	"4000"
DATABASE_PORT	5432	"5432"
DATABASE_SYNC	false	"false"
DATABASE_LOGGING	false	"false"
REDIS_PORT	6379	"6379"
REDIS_DB	0	"0"
BCRYPT_ROUNDS	10	"10"
SESSION_TIMEOUT_MS	7200000	"7200000"
RATE_LIMIT_TTL	60	"60"
RATE_LIMIT_MAX	100	"100"

💡 Comment l'application interprète les valeurs ?

Ne vous inquiétez pas ! Même si les variables sont des strings, l'application NestJS les convertira automatiquement au bon type :

// Dans le code NestJS
const port = parseInt(process.env.PORT, 10);           // "4000" → 4000
const dbPort = parseInt(process.env.DATABASE_PORT, 10); // "5432" → 5432
const dbSync = process.env.DATABASE_SYNC === 'true';   // "false" → false
const redisDb = parseInt(process.env.REDIS_DB, 10);    // "0" → 0

Le module @nestjs/config et les validateurs class-validator gèrent cette conversion automatiquement.

🧪 Test de Validation

Pour vérifier que votre portainer-stack.yml est correct :

# 1. Vérifier la syntaxe YAML
docker-compose -f docker/portainer-stack.yml config

# 2. Vérifier qu'il n'y a pas d'erreurs de validation
# (Devrait afficher la configuration sans erreur)

Si vous voyez des erreurs comme :

• must be a string
• must be a number
• must be null

Alors il faut ajouter des guillemets autour de la valeur.

📋 Checklist de Vérification

Avant de déployer sur Portainer, vérifier que :

• Tous les ports sont entre guillemets : "4000", "5432", "6379"
• Tous les booléens sont entre guillemets : "true", "false"
• Tous les nombres sont entre guillemets : "10", "0", "7200000"
• Les strings peuvent rester sans guillemets ou avec : preprod ou "preprod"
• Les URLs peuvent rester sans guillemets : https://api.preprod.xpeditis.com

⚠️ Exception : PostgreSQL et Redis

Pour les services PostgreSQL et Redis, certaines valeurs peuvent rester sans guillemets car elles sont utilisées par les images officielles qui sont plus permissives :

# PostgreSQL - OK sans guillemets
environment:
  POSTGRES_DB: xpeditis_preprod
  POSTGRES_USER: xpeditis
  POSTGRES_PASSWORD: 9Lc3M9qoPBeHLKHDXGUf1

# Redis - Commande avec guillemets pour la sécurité
command: redis-server --requirepass hXiy5GMPswMtxMZujjS2O --appendonly yes

Mais pour votre application backend, utilisez toujours des guillemets pour les valeurs non-string.

🔗 Références

• Docker Compose Environment Variables
• Portainer Stack Deployment
• YAML Specification

📄 Fichier Corrigé

Le fichier docker/portainer-stack.yml a été corrigé avec toutes les valeurs en strings.

Avant déploiement, vérifier que le fichier ne contient plus de valeurs booléennes ou numériques brutes dans la section environment du service xpeditis-backend.

---

Date : 2025-11-19 Version : 1.1 Statut : ✅ Corrigé et prêt pour déploiement