Variables d'environnement

Cette fiche recense les variables d'environnement lues par TimePick au démarrage : serveur (server/.env) et client (client/.env — build-time uniquement). Elle ne couvre pas le pas-à-pas d'installation (voir Partie 1 — Installation) ni le détail par fournisseur SMTP (voir SMTP — Fournisseurs).

Deux catégories de réglages

TimePick sépare la configuration d'infrastructure (variables d'environnement, lues une fois au démarrage) des réglages applicatifs (stockés en base de données, modifiables à chaud depuis l'écran Paramètres). Cette distinction revient tout au long de la fiche — voir Paramètres in-app.

Variables serveur (server/.env)

Le fichier server/.env.example du dépôt sert de modèle ; le copier vers server/.env puis renseigner les valeurs.

Variable	Rôle	Requise	Défaut
DATABASE_URL	Chaîne de connexion PostgreSQL (postgresql://user:password@hôte:5432/timepick)	Oui	—
PORT	Port d'écoute du serveur Express	Non	3000
JWT_SECRET	Secret de signature des JWT (sessions admin)	Oui	—
APP_URL	URL de base du frontend, utilisée pour construire les liens de connexion (magic links) et les boutons d'action des emails	Non	http://localhost:5173
EMAIL_FROM	Adresse d'expéditeur par défaut, utilisée quand aucune adresse SMTP n'est configurée en base	Non	noreply@example.com
ENCRYPTION_KEY	Clé de chiffrement (32 octets = 64 caractères hexadécimaux), utilisée pour chiffrer le mot de passe SMTP stocké en base	Oui	—

JWT_SECRET et ENCRYPTION_KEY sont obligatoires

Sans JWT_SECRET, le serveur refuse de démarrer (le chargement des modules d'authentification échoue immédiatement). Sans ENCRYPTION_KEY, le serveur démarre mais toute opération touchant au mot de passe SMTP (enregistrement, envoi authentifié) échoue — avec une erreur explicite en production. En pratique, les deux sont indispensables sur toute instance, et ENCRYPTION_KEY doit être une valeur générée spécifiquement pour l'instance — jamais la valeur d'exemple de .env.example.

ENCRYPTION_KEY sert au chiffrement du mot de passe SMTP en base (AES-256-GCM côté serveur). Une clé absente ou mal formée (longueur différente de 64 caractères hexadécimaux) fait échouer le chiffrement.

Générer les secrets

Générer JWT_SECRET et ENCRYPTION_KEY avec openssl, un bloc de commande à la fois :

openssl rand -hex 32

Exécuter la commande une première fois pour JWT_SECRET :

openssl rand -hex 32

Puis une seconde fois, séparément, pour ENCRYPTION_KEY (ne jamais réutiliser la même valeur pour les deux) :

openssl rand -hex 32

Chaque exécution produit une chaîne de 64 caractères hexadécimaux — coller le résultat tel quel dans server/.env.

Variables SMTP — provisionnement initial

Les sept variables SMTP_* de server/.env ne servent qu'au premier démarrage du serveur. À ce moment, elles sont copiées telles quelles dans la table app_config de la base de données ; ensuite, la configuration SMTP se gère exclusivement dans l'application (écran Paramètres → onglet Serveur d'email — voir Paramètres in-app).

Provisionnement one-shot

Une fois la copie effectuée, modifier les variables SMTP_* dans server/.env n'a plus aucun effet : le runtime lit la configuration en base, pas les variables d'environnement. Pour changer les paramètres SMTP après l'installation initiale, utiliser l'écran Paramètres.

Variable (.env)	Clé app_config correspondante	Rôle
SMTP_HOST	smtp_host	Hôte du serveur SMTP
SMTP_PORT	smtp_port	Port SMTP
SMTP_SECURE	smtp_secure	TLS activé (true/false)
SMTP_USER	smtp_user	Identifiant SMTP
SMTP_PASSWORD	smtp_password	Mot de passe SMTP (chiffré en base avec ENCRYPTION_KEY)
SMTP_FROM_NAME	smtp_from_name	Nom d'expéditeur affiché (défaut : TimePick)
SMTP_FROM_EMAIL	smtp_from_email	Adresse d'expéditeur SMTP

Le détail des réglages disponibles par fournisseur (Gmail, Brevo, OVH…) est traité dans SMTP — Fournisseurs.

Cascade de résolution SMTP

Au moment d'envoyer un email, le serveur détermine le transport SMTP à utiliser selon l'ordre suivant :

1. Base de données (app_config) — priorité la plus haute ; c'est la source utilisée en production dès que le provisionnement initial a eu lieu.
2. Variables SMTP_* de server/.env — utilisées uniquement si la base ne contient aucune configuration SMTP, et uniquement hors production.
3. Variables historiques EMAIL_HOST / EMAIL_PORT — repli de compatibilité ascendante, également limité aux environnements non-production.
4. Repli MailHog (127.0.0.1:1025) en développement/test si aucune des sources précédentes n'est renseignée ; en production, l'absence de configuration en base désactive l'envoi d'emails (aucun repli).

À confirmer

Cette cascade est vérifiée dans le code (server/src/services/email-transport.service.ts) et par un test de bout en bout avec MailHog sur l'instance de référence. Un envoi via un fournisseur SMTP réel (Gmail, Brevo, OVH…) n'a pas encore été testé de bout en bout — toute configuration SMTP décrite ailleurs dans cette documentation porte la mention « à confirmer » tant qu'elle n'a pas été validée avec un compte réel.

Variable client (client/.env)

Variable	Rôle	Requise	Défaut
VITE_API_URL	URL complète de l'API backend	Non	http://localhost:3000/api

VITE_API_URL est une variable de build, pas de runtime

Vite intègre VITE_API_URL dans le bundle JavaScript au moment de la compilation (npm run build). La modifier après coup dans un conteneur déjà construit n'a aucun effet : il faut reconstruire l'image avec la bonne valeur. Voir Installation en production (Docker) pour la procédure de build avec cette variable.

Infrastructure vs réglages applicatifs

Pour résumer la distinction évoquée en introduction :

• Infrastructure (.env / variables du conteneur, lues au démarrage, redémarrage requis pour tout changement) : DATABASE_URL, PORT, JWT_SECRET, APP_URL, EMAIL_FROM, ENCRYPTION_KEY, VITE_API_URL, ainsi que les variables SMTP_* — mais uniquement pour leur rôle de provisionnement initial.
• Applicatif (table app_config, modifiable à chaud depuis l'écran Paramètres, sans redémarrage) : nom et description de l'organisation, logo, intervalle de polling du calendrier, durées de vie des liens de connexion et des sessions, et — une fois le provisionnement initial effectué — la configuration SMTP complète.

Le détail des réglages applicatifs et de l'écran Paramètres est couvert dans Configuration initiale et Paramètres in-app.