unionflow-server-impl-quarkus/VARIABLES_ENVIRONNEMENT.md

🔐 Variables d'Environnement - UnionFlow

Date : 17 novembre 2025
Objectif : Documenter toutes les variables d'environnement nécessaires

---

📋 UnionFlow Client

Variables Requises

Variable	Description	Exemple	Où l'obtenir
KEYCLOAK_CLIENT_SECRET	Secret du client Keycloak unionflow-client	7dnWMwlabtoyp08F6FIuDxzDPE5VdUF6	Keycloak Admin Console
UNIONFLOW_BACKEND_URL	URL du backend (optionnel, défaut: http://localhost:8085)	http://localhost:8085	-

Variables Optionnelles

Variable	Description	Valeur par défaut
SESSION_TIMEOUT	Timeout de session en secondes	1800 (30 min)
REMEMBER_ME_DURATION	Durée "Se souvenir de moi" en secondes	604800 (7 jours)
ENABLE_CSRF	Activer la protection CSRF	true
PASSWORD_MIN_LENGTH	Longueur minimale du mot de passe	8
PASSWORD_REQUIRE_SPECIAL	Exiger des caractères spéciaux	true
MAX_LOGIN_ATTEMPTS	Nombre max de tentatives de connexion	5
LOCKOUT_DURATION	Durée de verrouillage en secondes	300 (5 min)

Comment obtenir le secret Keycloak

1. Se connecter à Keycloak Admin Console

   • URL : https://security.lions.dev/admin
   • Realm : unionflow

2. Naviguer vers le client

   • Menu : Clients → unionflow-client

3. Récupérer le secret

   • Onglet : Credentials
   • Copier le Client Secret

4. Définir la variable d'environnement

   # Windows PowerShell
   $env:KEYCLOAK_CLIENT_SECRET="votre-secret-ici"
   
   # Linux/Mac
   export KEYCLOAK_CLIENT_SECRET="votre-secret-ici"
   

---

📋 UnionFlow Server

Variables Requises

Variable	Description	Exemple	Où l'obtenir
KEYCLOAK_CLIENT_SECRET	Secret du client Keycloak unionflow-server	unionflow-secret-2025	Keycloak Admin Console
DB_PASSWORD	Mot de passe de la base de données PostgreSQL	unionflow123	Configuration DB
DB_USERNAME	Nom d'utilisateur de la base de données (optionnel, défaut: unionflow)	unionflow	Configuration DB
DB_URL	URL de connexion à la base de données (optionnel, défaut: jdbc:postgresql://localhost:5432/unionflow)	jdbc:postgresql://localhost:5432/unionflow	Configuration DB

Variables Optionnelles

Variable	Description	Valeur par défaut
DB_PASSWORD_DEV	Mot de passe DB pour développement	skyfile
CORS_ORIGINS	Origines CORS autorisées (séparées par virgules)	http://localhost:8086,https://unionflow.lions.dev,https://security.lions.dev

Comment obtenir le secret Keycloak (Server)

1. Se connecter à Keycloak Admin Console

   • URL : https://security.lions.dev/admin (ou http://localhost:8180 pour dev local)
   • Realm : unionflow

2. Naviguer vers le client

   • Menu : Clients → unionflow-server

3. Récupérer le secret

   • Onglet : Credentials
   • Copier le Client Secret

---

🚀 Configuration pour Développement Local

Option 1 : Variables d'environnement système

Windows PowerShell :

$env:KEYCLOAK_CLIENT_SECRET="7dnWMwlabtoyp08F6FIuDxzDPE5VdUF6"
$env:DB_PASSWORD="skyfile"

Linux/Mac :

export KEYCLOAK_CLIENT_SECRET="7dnWMwlabtoyp08F6FIuDxzDPE5VdUF6"
export DB_PASSWORD="skyfile"

Option 2 : Fichier .env (si supporté)

Créez un fichier .env à la racine du projet avec :

KEYCLOAK_CLIENT_SECRET=7dnWMwlabtoyp08F6FIuDxzDPE5VdUF6
DB_PASSWORD=skyfile

⚠️ IMPORTANT : Le fichier .env est déjà dans .gitignore et ne sera jamais commité.

Option 3 : Valeurs par défaut dans application-dev.properties

Pour le développement uniquement, des valeurs par défaut sont configurées dans application-dev.properties :

• Client : Secret Keycloak avec valeur par défaut
• Server : Mot de passe DB avec valeur par défaut

⚠️ ATTENTION : Ces valeurs par défaut sont UNIQUEMENT pour le développement local. En production, utilisez toujours des variables d'environnement.

---

🔒 Sécurité en Production

⚠️ RÈGLES IMPORTANTES

1. NE JAMAIS commiter de secrets dans Git
2. TOUJOURS utiliser des variables d'environnement en production
3. NE JAMAIS utiliser les valeurs par défaut en production
4. UTILISER un gestionnaire de secrets (Vault, AWS Secrets Manager, etc.)

Configuration Production Recommandée

# Utiliser un gestionnaire de secrets
# Exemple avec Kubernetes Secrets
kubectl create secret generic unionflow-secrets \
  --from-literal=KEYCLOAK_CLIENT_SECRET='votre-secret' \
  --from-literal=DB_PASSWORD='votre-mot-de-passe'

---

🐛 Dépannage

Erreur : "Invalid client or Invalid client credentials"

Cause : Le secret Keycloak n'est pas fourni ou est incorrect.

Solutions :

1. Vérifier que la variable KEYCLOAK_CLIENT_SECRET est définie
2. Vérifier que le secret correspond au client dans Keycloak
3. Vérifier que le client existe dans Keycloak
4. Vérifier que le client est activé dans Keycloak

Erreur : "Connection refused" ou "Cannot connect to database"

Cause : La base de données n'est pas accessible ou les credentials sont incorrects.

Solutions :

1. Vérifier que PostgreSQL est démarré
2. Vérifier que les variables DB_USERNAME, DB_PASSWORD, DB_URL sont correctes
3. Vérifier la connectivité réseau vers la base de données

---

Date de création : 17 novembre 2025
Dernière mise à jour : 17 novembre 2025