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 comporte deux étapes numérotées — 1. Serveur SMTP puis 2. Administrateur — la seconde se concluant par un écran de confirmation.

Étape 1 — 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 au minimum, pour continuer : en mode SMTP, un hôte et un port valides (1–65535) ; en mode HTTP, les champs requis du fournisseur choisi (au moins une clé API) ainsi qu'un email expéditeur ;
• propose un bouton Tester la connexion, qui envoie un email de test à une adresse indiquée — cette étape est recommandée mais pas obligatoire pour passer à la suite ;
• 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 2 — Email du premier administrateur

Saisie de l'adresse email qui deviendra le compte administrateur. Un clic sur Devenir administrateur appelle POST /api/setup/create-admin, qui déclenche l'envoi du lien d'amorçage (voir section suivante).

É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 1) 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 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 /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 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.

Déroulé vérifié

Le parcours a été rejoué de bout en bout sur l'instance de référence le 2026-07-18 : le serveur détecte Mailpit (emailDeliverable vrai), l'étape SMTP est sautée via « Passer cette étape », l'administrateur est créé, le lien d'amorçage arrive dans Mailpit (interface :8025) et son clic redirige vers le tableau de bord. Le cas inverse a aussi été vérifié : en mode production sans configuration SMTP en base, le signal repasse à faux et l'étape redevient 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 ;
• promeut l'utilisateur existant vers le rôle admin s'il a déjà un compte membre ;
• 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.

Ne pas passer l'email en argument

D'anciennes versions du script acceptaient l'email en argument de ligne de commande (npm run create-admin -- admin@exemple.com). Cette forme est obsolète : lancer le script sans argument et répondre aux invites interactives.

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	Hôte, port ou identifiants SMTP incorrects à l'étape 1	Revenir à l'étape SMTP (« Modifier la configuration SMTP ») et utiliser Tester la connexion avant de continuer
« 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