Variables d'environnement — Référence complète

English version
← Retour au sommaire

Format du fichier `.app_env` (production)

En production (Docker Compose), les variables sont chargées depuis un fichier .app_env :

# Toutes les valeurs entre double quotes — obligatoire
PG_HOST="postgres"
PG_PORT="5432"
PG_DATABASE="racines"
PG_USER="postgres"
PG_PASSWORD="votre_mot_de_passe_secure"
PG_SSL="false"
JWT_SECRET="votre_secret_jwt_très_long_et_aléatoire"
AUDIO_CDN_URL="https://racines-s3.id2real.net/audios"
AUDIO_CDN_DOMAIN="racines-s3.id2real.net"

⚠️ Les valeurs avec des caractères spéciaux (#, =, espaces) doivent être entre double quotes pour être correctement interprétées.

Développement local — `.env.local`

# PostgreSQL
PG_HOST=localhost
PG_PORT=5432
PG_DATABASE=racines
PG_USER=postgres
PG_PASSWORD=postgres
PG_SSL=false

# MinIO
MINIO_ENDPOINT=localhost
MINIO_PORT=9000
MINIO_USE_SSL=false
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=audios
MINIO_PUBLIC_URL=http://localhost:9000

# Auth
JWT_SECRET=dev_secret_not_for_production

# Audio CDN (en dev, utilise le proxy fallback)
AUDIO_CDN_URL=
AUDIO_PROXY_DISABLED=false

# PWA (désactivé en dev par défaut)
NEXT_PUBLIC_PWA_ENABLED=false

Référence complète des variables

Groupe PostgreSQL

Variable	Obligatoire	Défaut	Description	Impact si absente
`PG_HOST`	✅	—	Hostname du serveur PostgreSQL	Connexion impossible → app crash
`PG_PORT`	✅	`5432`	Port PostgreSQL	Connexion impossible
`PG_DATABASE`	✅	`racines`	Nom de la base de données	Connexion impossible
`PG_USER`	✅	—	Utilisateur PostgreSQL	Connexion impossible
`PG_PASSWORD`	✅	—	Mot de passe PostgreSQL	Connexion impossible
`PG_SSL`	❌	`false`	Activer SSL (`true`/`false`)	Connexion non chiffrée si false

Configuration du pool (non configurable via env, hardcodé dans src/lib/postgres.ts) : - Max connexions : 20 - Timeout idle : 30s - Timeout connexion : 10s

Groupe MinIO

Variable	Obligatoire	Défaut	Description	Impact si absente
`MINIO_ENDPOINT`	✅	—	Hostname du serveur MinIO	Upload audio impossible
`MINIO_PORT`	❌	`9000`	Port de l'API MinIO	—
`MINIO_USE_SSL`	❌	`false`	HTTPS pour l'API MinIO	Connexion non chiffrée
`MINIO_ACCESS_KEY`	✅	—	Clé d'accès MinIO	Upload impossible
`MINIO_SECRET_KEY`	✅	—	Clé secrète MinIO	Upload impossible
`MINIO_BUCKET`	✅	`audios`	Nom du bucket de stockage	Upload vers mauvais bucket
`MINIO_PUBLIC_URL`	✅	—	URL publique de MinIO (pour les URLs audio en dev)	URLs audio invalides

Groupe Audio / CDN

🔴 Variables critiques — lire attentivement

Variable	Obligatoire	Défaut	Description
`AUDIO_CDN_URL`	Oui en production	—	URL complète du CDN audio MinIO
`AUDIO_PROXY_DISABLED`	❌	`false`	Désactiver le proxy fallback Next.js
`AUDIO_CDN_DOMAIN`	❌ (auto-dérivé)	—	Hostname extrait de `AUDIO_CDN_URL`

AUDIO_CDN_URL — détails critiques :

Lue par : RootLayout (Server Component, force-dynamic) à chaque requête SSR
Injectée dans : window.__RACINES_CDN__ comme premier <script> de <head>, avant tout chunk client
Lue par le client : src/lib/audio-url.ts → getAudioUrl()
Impact si vide : getAudioUrl() retourne '' → les URLs audio sont vides → requêtes parasites vers la page courante → tous les audios silencieux
L'entrypoint Docker (docker/entrypoint.sh) refuse de démarrer si cette variable est vide

# Exemple production
AUDIO_CDN_URL=https://racines-s3.id2real.net/audios

# Exemple développement (utilise le proxy)
AUDIO_CDN_URL=   # vide → proxy activé automatiquement

AUDIO_PROXY_DISABLED :

Valeur	Comportement
`false` (défaut)	Si `AUDIO_CDN_URL` vide → proxy `/api/audio/serve/` actif
`true`	Proxy désactivé — `AUDIO_CDN_URL` doit être renseigné

⚠️ AUDIO_PROXY_DISABLED=true + AUDIO_CDN_URL= (vide) = bug silencieux — tous les audios sont silencieux sans erreur visible.

AUDIO_CDN_DOMAIN : - Hostname extrait de AUDIO_CDN_URL (ex : racines-s3.id2real.net) - Utilisé dans la Content Security Policy (media-src, connect-src) - Si absent, l'entrypoint.sh le dérive automatiquement depuis AUDIO_CDN_URL - Peut être surchargé explicitement si le domaine CDN diffère du domaine MinIO

Groupe Authentification

Variable	Obligatoire	Description	Impact si absente
`JWT_SECRET`	✅	Clé secrète pour signer les JWT admin (HS256)	Tokens invalides → tous les admins déconnectés

Recommandations : - Minimum 32 caractères aléatoires - Générer avec : openssl rand -base64 32 - Changer invalide toutes les sessions actives (re-login obligatoire)

Groupe Email (optionnel)

Ces variables sont nécessaires si vous souhaitez que le formulaire de contact envoie des notifications email.

Variable	Obligatoire	Description
`SMTP_HOST`	❌	Hostname du serveur SMTP
`SMTP_PORT`	❌	Port SMTP (ex : `587`)
`SMTP_USER`	❌	Utilisateur SMTP
`SMTP_PASSWORD`	❌	Mot de passe SMTP
`SMTP_FROM`	❌	Adresse email expéditeur (ex : `noreply@racines.app`)

Si ces variables sont absentes, le formulaire de contact enregistre les messages en base mais n'envoie pas d'email de notification.

Variables `NEXT_PUBLIC_*` (build-time)

Ces variables sont intégrées dans le bundle JavaScript au moment du build. Elles ne peuvent pas être modifiées à chaud après le build.

Variable	Défaut	Description
`NEXT_PUBLIC_PWA_ENABLED`	`true` (en prod)	Active le manifest PWA et les métadonnées Apple. Mettre `false` en dev pour éviter les conflits SW.

Variables CI/CD GitLab (secrets)

Ces variables sont configurées dans GitLab → Settings → CI/CD → Variables. Elles ne sont jamais commitées dans le dépôt.

Variable	Description
`DEPLOY_HOST`	Hostname du serveur de production
`DEPLOY_USER`	Utilisateur SSH de déploiement
`DEPLOY_KEY`	Clé SSH privée pour le déploiement
`REGISTRY_URL`	URL du GitLab Container Registry
`DOCKER_AUTH_CONFIG`	Config d'authentification Docker Registry

Vérification rapide

# Vérifier les variables dans le container en cours d'exécution
docker exec racines-app env | grep -E "PG_|MINIO_|AUDIO_|JWT_"

# Vérifier que AUDIO_CDN_URL est bien défini
docker exec racines-app sh -c 'echo $AUDIO_CDN_URL'

# Health check
curl http://localhost:3000/api/health/live