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 les paramètres SMTP (hôte, port, sécurité, identifiants, nom et adresse d'expédition). Ce formulaire :

• 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 un hôte et un port valides (1–65535) pour continuer ;
• 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 (MailHog)

L'étape SMTP de l'assistant n'a pas de bouton « passer » : un hôte et un port valides doivent être renseignés pour avancer. En développement, la pratique courante consiste à renseigner les paramètres du serveur de capture MailHog (hôte localhost, port 1025) plutôt qu'un vrai fournisseur SMTP — MailHog accepte n'importe quelle connexion SMTP sans authentification et intercepte les emails, y compris celui du lien d'amorçage. Le bouton Tester la connexion n'étant pas obligatoire pour continuer, il est possible d'avancer dans l'assistant sans l'utiliser, à condition que l'envoi réel (déclenché à l'étape 2) atteigne un serveur SMTP joignable.

Déroulé vérifié

Ce parcours complet (étape SMTP renseignée avec MailHog, test de connexion, création puis clic sur le lien d'amorçage, redirection vers le tableau de bord) a été rejoué intégralement sur l'instance de référence le 2026-07-13.

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