Configuration initiale (première utilisation)

Au tout premier démarrage d'une instance TimePick, la base de données ne contient aucun administrateur. L'application détecte automatiquement cet état et guide vers la création du premier compte admin. Cette fiche décrit les deux façons d'effectuer cette configuration initiale : l'assistant web (/setup) et le script en ligne de commande. Pour le détail des variables d'environnement (dont les variables SMTP_* de provisionnement au premier démarrage Docker), voir Variables d'environnement.

Détection automatique et redirection

À chaque chargement, l'interface interroge GET /api/setup/status, qui renvoie :

{ "needsSetup": true }

needsSetup vaut true tant qu'aucun utilisateur n'a le rôle admin en base. Dans ce cas :

• toute page visitée redirige automatiquement vers /setup, à l'exception de /setup lui-même, des URLs publiques /events/:uuid (calendrier public d'un événement) et de la page interne /design-system (outil de développement) ;
• un utilisateur déjà authentifié n'est jamais redirigé vers /setup — sa seule existence signifie qu'un admin existe déjà, donc que la configuration est terminée.

Dès qu'un premier admin existe, needsSetup repasse à false et visiter /setup redirige vers la page de connexion (/login).

Vérifier le statut depuis la ligne de commande

Utile pour confirmer qu'une instance fraîchement déployée attend bien sa configuration initiale, sans passer par le navigateur :

curl https://timepick.example.org/api/setup/status

Réponse attendue sur une instance neuve : {"needsSetup":true}. Une fois le premier admin créé : {"needsSetup":false}.

L'assistant web (/setup)

L'assistant enchaîne trois étapes — Votre organisation, Serveur SMTP, Administrateur — la dernière se concluant par un écran de confirmation. Une quatrième, Clé de chiffrement, les précède uniquement lorsque le serveur a généré la clé lui-même dans un fichier (voir Variables d'environnement) : elle affiche l'empreinte de la clé à noter, et ne demande rien d'autre qu'un Continuer. Un bouton Précédent permet de revenir en arrière depuis chaque étape sauf la première ; reculer n'enregistre rien, et la saisie déjà effectuée sur l'étape reste affichée si l'on y revient ensuite.

Étape « Votre organisation »

Nom, logo et description de l'organisation, destinés à personnaliser la page d'accueil publique de l'instance. Le nom est facultatif : la description seule peut être enregistrée sans lui. Un seul bouton, Continuer, enregistre en une fois tout ce qui est saisi à l'écran — jamais au fil de la frappe — puis passe à l'étape suivante ; vider un champ avant de cliquer efface la valeur déjà enregistrée. Sans nom d'organisation, la page d'accueil publique n'affiche rien de personnalisé aux visiteurs et redirige vers la connexion (/login) — la description et le logo, eux, restent enregistrés, et tout reste modifiable ensuite depuis Paramètres → Organisation. Le logo fait exception à la règle du bouton unique : il s'enregistre dès son dépôt, l'aperçu l'exigeant immédiatement ; il peut ensuite être remplacé ou supprimé à tout moment.

Étape « Serveur d'email (SMTP) »

Avant de pouvoir créer un administrateur, l'assistant demande la configuration du serveur d'email. Ce formulaire :

• s'ouvre sur un sélecteur Mode d'envoi — SMTP (défaut) ou Envoi par API (HTTP), ce dernier avec un sous-menu de fournisseur (Brevo, Mailjet, Scaleway, Sweego, Resend) ; en mode HTTP, les champs SMTP laissent place au formulaire d'identifiants du fournisseur choisi (une clé API, ou une clé + un secret selon le fournisseur — voir Fournisseurs SMTP — Envoi par API (HTTP)) ;
• se pré-remplit avec la configuration déjà présente en base, le cas échéant (par exemple les variables SMTP_* provisionnées au premier démarrage d'un conteneur Docker — voir Installation en production (Docker)) ; sur une base vierge sans provisionnement, le champ hôte reste vide et le port affiche 587 par défaut ;
• exige, pour continuer : en mode SMTP, un hôte et un port valides (1–65535) ainsi qu'un email expéditeur ; en mode HTTP, les champs requis du fournisseur choisi (au moins une clé API) ainsi qu'un email expéditeur ;
• exige en plus un test de connexion réussi dès qu'un serveur d'envoi est renseigné : Continuer reste désactivé — avec le motif affiché juste à côté du bouton — tant que Tester la connexion n'a pas abouti sur les valeurs saisies. La preuve expire dès qu'un champ change : il faut alors retester. Une configuration syntaxiquement correcte mais injoignable ne peut donc plus être enregistrée pour n'échouer qu'à l'étape suivante ;
• envoie, via Tester la connexion, un véritable email à l'adresse indiquée (pré-remplie avec l'email de l'expéditeur, modifiable). En cas d'échec, le message nomme la cause précise (connexion refusée, délai d'attente dépassé, authentification refusée, hôte introuvable, échec TLS) plutôt que de recopier l'erreur technique brute. Un refus pour cause de quota (trop de tests en une minute) est toujours signalé comme tel, jamais confondu avec un échec de connexion ;
• affiche un bouton Effacer la configuration enregistrée (DELETE /api/setup/smtp) dès qu'une configuration existe en base. Il la supprime et rend la main au serveur d'envoi détecté automatiquement s'il y en a un. C'est la sortie prévue lorsqu'une configuration enregistrée se révèle injoignable : vider le champ « Hôte SMTP » à la main n'y suffit pas, puisque l'hôte redevient alors simplement obligatoire ;
• enregistre la configuration (PUT /api/setup/smtp) au clic sur Continuer, avant de passer à l'étape suivante.

Cette étape ne détaille pas les fournisseurs SMTP

Le paramétrage propre à chaque fournisseur (Gmail, Brevo, OVH…) est détaillé dans Fournisseurs SMTP. Cette fiche-ci ne couvre que le mécanisme de l'assistant.

Étape « Identité du premier administrateur »

Saisie du prénom (requis), du nom (facultatif) et de l'adresse email qui deviendra le compte administrateur. Les deux champs de nom sont bornés à 100 caractères, côté formulaire comme côté serveur. Un clic sur Devenir administrateur appelle POST /api/setup/create-admin, qui déclenche l'envoi du lien d'amorçage (voir section suivante).

Ces noms servent immédiatement : l'email d'amorçage s'adresse nommément à la personne (« Bonjour Prénom, »), et le compte créé au clic du lien les porte — inutile de compléter son profil après coup.

Écran de confirmation

Une fois le lien envoyé, le formulaire laisse place à un message de confirmation (« Un lien d'activation a été envoyé à … »), avec deux actions possibles : Modifier la configuration SMTP (retour à l'étape SMTP) et Renvoyer / changer d'email.

Le lien d'amorçage

POST /api/setup/create-admin n'enregistre pas encore le compte administrateur. Il génère un jeton (JWT) signé, valable 24 heures, et l'envoie par email dans un lien de connexion (/login?token=…) — le même mécanisme que les magic links utilisés pour l'authentification courante, avec un champ interne marquant qu'il s'agit d'un jeton d'amorçage. Le prénom et le nom saisis au formulaire voyagent dans ce jeton : c'est ainsi qu'ils atteignent la création du compte, différée au clic.

Le compte n'est créé qu'au moment où ce lien est effectivement cliqué : la validation du jeton (POST /api/auth/verify) déclenche alors la création de l'administrateur de façon atomique — dans une seule transaction protégée par un verrou PostgreSQL (advisory lock). Concrètement, cela rend impossible la création de deux « premiers administrateurs » en parallèle : si deux personnes cliquent le lien au même instant (ou si le formulaire est soumis deux fois), une seule création aboutit.

• Si une autre création est en cours au même instant, la tentative concurrente reçoit une erreur invitant à réessayer quelques secondes plus tard.
• Si un administrateur a déjà été créé entre-temps, la tentative échoue avec un message invitant à se connecter normalement.

Une fois la création réussie, la connexion s'effectue automatiquement et redirige vers le tableau de bord administrateur.

Fenêtre de sécurité du premier démarrage

Entre le démarrage de l'instance et la création du premier administrateur, /setup est accessible sans authentification à quiconque atteint l'URL publique de l'instance. Sur un déploiement de production, il est recommandé de finaliser cette étape immédiatement après le premier démarrage plutôt que de laisser l'instance exposée sans admin pendant une longue période. Voir Déploiement sur un VPS avec Coolify pour l'enchaînement recommandé entre démarrage du conteneur et configuration initiale.

Sécurité une fois le premier admin créé

Dès qu'un administrateur existe en base, les routes de configuration initiale (POST /api/setup/create-admin, GET/PUT/DELETE /api/setup/smtp, POST /api/setup/smtp/test) répondent systématiquement 404, sans distinction avec une route inexistante — aucune information sur l'état de l'instance n'est divulguée à un visiteur non authentifié. Côté interface, visiter /setup à ce stade redirige simplement vers la page de connexion.

Cas particulier : environnement de développement (intercepteur SMTP local)

Depuis l'ajout d'un signal de délivrabilité serveur, l'étape SMTP de l'assistant devient sautable (tout en restant affichée et configurable, jamais masquée) dès que le serveur détecte, via une sonde SMTP courte effectuée à l'ouverture de l'assistant, qu'un serveur d'envoi répond déjà. Le message de l'étape précise ce qui a été détecté : une configuration SMTP déjà enregistrée en base (champs pré-remplis), un serveur défini par les variables d'environnement, ou un intercepteur local répondant sur 127.0.0.1:1025 — en pratique Mailpit, lancé par défaut en développement. Concrètement : cliquer sur « Passer cette étape » sans renseigner d'hôte passe directement à l'étape suivante (rien n'est enregistré), tandis que renseigner un hôte (ou choisir le fournisseur Resend dans le sélecteur) réactive la validation classique — test de connexion réussi compris — et enregistre normalement, utile pour configurer malgré tout un vrai fournisseur d'email à cette étape. Si rien ne répond (Mailpit arrêté, par exemple), la sonde échoue et l'étape redevient requise comme pour tout environnement sans serveur d'email détecté : jamais d'échec silencieux.

Une configuration SMTP enregistrée en base prend le pas sur l'intercepteur local : tant qu'un hôte est enregistré, c'est lui qui est sondé, et le saut d'étape disparaît s'il ne répond pas. Le bouton Effacer la configuration enregistrée est la sortie : il supprime la configuration, la sonde retrouve l'intercepteur local et le saut d'étape redevient disponible — sans intervention en base ni en ligne de commande.

Déroulé vérifié

Le parcours a été rejoué de bout en bout sur l'instance de référence le 2026-07-29. Le serveur détecte Mailpit (emailDeliverable vrai) et l'étape SMTP propose « Passer cette étape ». Un hôte injoignable (127.0.0.1:1026), saisi puis testé, produit le message « Connexion refusée… » ; Continuer reste alors désactivé, avec le motif « La connexion a échoué. Corrigez les paramètres puis retestez. » — rien n'est enregistré en base. Une configuration injoignable présente en base fait bien disparaître le saut d'étape. Effacer la configuration enregistrée rétablit l'état initial (champs vides, « Passer cette étape » de retour) sans aucune intervention hors interface. Le cas production sans configuration SMTP en base reste vérifié : le signal est faux et l'étape est requise.

Alternative : script en ligne de commande

Pour créer un administrateur sans passer par l'interface web — utile pour un déploiement automatisé ou en cas de problème d'accès à /setup — TimePick fournit un script interactif qui se connecte directement à la base de données (le serveur applicatif n'a pas besoin d'être démarré).

Depuis la racine du projet :

cd server

npm run create-admin

Le script demande l'email de l'administrateur à créer ou promouvoir, puis :

• crée un nouvel administrateur si l'email ne correspond à aucun utilisateur existant — il demande alors son prénom (requis) et son nom (facultatif) ;
• promeut l'utilisateur existant vers le rôle admin s'il a déjà un compte membre — aucune question de nom n'est posée, son identité est préservée ;
• ne fait rien si l'utilisateur est déjà administrateur.

L'opération est atomique (transaction avec verrouillage de ligne), au même titre que la création via le lien d'amorçage.

Passer l'email en argument

npm run create-admin -- admin@exemple.com pré-remplit l'email et saute la première question ; les questions suivantes restent posées. Hors terminal interactif (pipe, tâche planifiée), le script s'arrête avec un message explicite dès qu'une saisie est nécessaire, plutôt que de rester bloqué.

Après la première connexion

Une fois connecté avec le premier compte administrateur, il est recommandé de générer immédiatement les codes de secours — un jeu de codes à usage unique permettant de se reconnecter si les emails de connexion ne sont plus reçus (panne SMTP, boîte mail inaccessible…). Ces codes se génèrent depuis la page de profil de l'administrateur, jamais envoyés par email.

Voir Sécurité pour le détail du mécanisme et Connexion de secours pour son usage côté utilisateur.

Dépannage

Symptôme	Cause probable	Piste
/setup ne s'affiche pas, redirection directe vers /login	Un administrateur existe déjà en base	Se connecter normalement, ou vérifier en base : SELECT email, role FROM users WHERE role='admin';
Erreur lors de l'envoi du lien, message évoquant la configuration SMTP	Serveur d'envoi provisionné par les variables SMTP_* (jamais testé depuis l'assistant), ou serveur qui accepte le test mais refuse l'envoi réel	Revenir à l'étape SMTP (« Modifier la configuration SMTP ») et utiliser Tester la connexion, qui envoie un vrai email et nomme la cause de l'échec
L'étape SMTP réclame un hôte et « Passer cette étape » a disparu	Une configuration injoignable est enregistrée en base : elle masque le serveur d'envoi détecté automatiquement	Cliquer Effacer la configuration enregistrée sur l'étape SMTP — vider le champ « Hôte SMTP » ne suffit pas
« Configuration en cours, réessayez » au clic sur le lien	Une autre création d'admin est en cours au même instant (verrou actif)	Attendre quelques secondes et recliquer le lien — le verrou se libère automatiquement en fin de transaction
« La configuration est déjà terminée » au clic sur le lien	Un autre admin a été créé entre l'envoi de l'email et le clic (ou double création)	Se connecter avec le compte administrateur effectivement créé

Pour un diagnostic plus large des problèmes d'envoi d'email (hors configuration initiale), voir Dépannage et Délivrabilité email.

Voir aussi

• Variables d'environnement — détail des variables SMTP_*, JWT_SECRET, APP_URL…
• Paramètres in-app — modification de la configuration SMTP après le premier démarrage
• Fournisseurs SMTP — configuration par fournisseur (Gmail, Brevo, OVH…)
• Sécurité — codes de secours, verrous et protections applicatives