Installation locale (développement)

Cette fiche décrit l'installation complète de TimePick sur votre poste de développement, du clonage du dépôt jusqu'à un serveur qui répond. Elle ne couvre ni le déploiement Docker/production (voir Installation en production (Docker) et Déploiement Coolify / VPS), ni le détail des fournisseurs SMTP (voir SMTP et fournisseurs).

Les prérequis (Node.js, PostgreSQL, outils) sont détaillés dans Prérequis — assurez-vous de les avoir installés avant de commencer.

1. Cloner le dépôt

git clone https://github.com/timepick-app/timepick.git

cd timepick

2. Installer les dépendances

npm install

WARNING

npm install doit être lancé uniquement à la racine du projet. TimePick est un monorepo à trois espaces de travail npm (client, server, shared) : cette seule commande installe les dépendances des trois d'un coup. N'installez jamais séparément dans client/, server/ ou shared/ — cela crée des arborescences node_modules incohérentes.

3. Configurer les variables d'environnement

Copiez le fichier d'exemple :

cp server/.env.example server/.env

Ouvrez ensuite server/.env et renseignez au minimum les variables suivantes :

Variable	Rôle	Exemple en développement
DATABASE_URL	Chaîne de connexion PostgreSQL	postgresql://user:password@localhost:5432/timepick
JWT_SECRET	Clé de signature des tokens de session	optionnel — généré automatiquement si absent (voir ci-dessous)
ENCRYPTION_KEY	Clé de chiffrement (mots de passe SMTP stockés en base)	optionnel — généré automatiquement si absent, 32 octets en hexadécimal (64 caractères)
APP_URL	URL du frontend, utilisée dans les liens des emails (magic link, boutons d'action)	http://localhost:5173
EMAIL_FROM	Adresse d'expédition par défaut des emails	noreply@example.org

TIP

La liste complète des variables (SMTP, polling, TTL de session…) est détaillée dans Variables d'environnement. Pour un premier lancement en local, les cinq variables ci-dessus suffisent.

Ces deux secrets n'ont pas besoin d'être renseignés manuellement : s'ils sont absents de server/.env, le serveur les génère automatiquement au premier démarrage et les stocke dans server/data/ (jwt.secret, encryption.key). Si la variable d'environnement correspondante est définie, elle est toujours prioritaire sur le fichier généré (l'ordre de priorité est environnement > fichier).

Pour gérer vous-même ces secrets (recommandé en production), générez-les manuellement avec openssl, un bloc de commande à la fois :

openssl rand -hex 32

Copiez le résultat dans JWT_SECRET.

openssl rand -hex 32

Copiez ce second résultat dans ENCRYPTION_KEY.

4. Initialiser la base de données

Placez-vous dans le dossier serveur :

cd server

Créez la base et son extension requise :

npm run init-db

Sortie attendue (symboles décoratifs omis) :

Creating database timepick...
Database timepick created.
UUID extension enabled.
Creating base users table...
Base users table created.
Users table trigger created.
Database initialization complete!
Next step: Run migrations with `npm run migrate`

WARNING

Si la commande échoue avec permission denied to create extension, l'utilisateur PostgreSQL configuré dans DATABASE_URL n'a pas les droits nécessaires pour créer l'extension uuid-ossp. Deux solutions : accorder temporairement les droits superutilisateur (psql -c "ALTER USER <utilisateur> SUPERUSER"), ou faire pré-installer l'extension par un administrateur PostgreSQL.

Appliquez ensuite les migrations :

npm run migrate

Cette commande applique l'intégralité des migrations SQL du projet (schéma des tables, contraintes, index) dans l'ordre. Le nombre de migrations évolue à chaque version ; consultez server/src/migrations/ pour la liste à jour si besoin.

5. (Optionnel) Charger des données de démonstration

npm run seed

DANGER

N'exécutez jamais cette commande sur une base contenant des données réelles : elle purge intégralement la table users avant de la re-remplir. La commande refuse de s'exécuter si NODE_ENV=production, et laisse un délai d'annulation de 3 secondes (Ctrl+C) avant de lancer la purge lorsqu'elle est lancée depuis un terminal interactif.

Le script ne crée ni événement ni créneau : il se limite à la table des utilisateurs, avec un jeu de comptes fictifs prêts à l'emploi (instantané juillet 2026 : 43 utilisateurs, dont 3 comptes administrateur et 40 membres). Cette étape est purement optionnelle et utile pour explorer l'interface sans créer manuellement des comptes de test.

6. Lancer l'application

Depuis la racine du projet :

npm run dev

Cette commande démarre trois processus en parallèle :

Processus	Rôle	URL
SHARED	Compilation en mode watch du package partagé @timepick/shared	—
CLIENT	Serveur de développement Vite (frontend React)	http://localhost:5173
SERVER	API Express	http://localhost:3000

Il est possible de démarrer un seul processus à la fois :

npm run dev:client

npm run dev:server

WARNING

Sur un clone tout juste installé, npm run dev:server seul peut échouer car le package partagé shared n'a encore jamais été compilé. npm run dev s'en charge automatiquement, mais si vous lancez dev:server ou dev:client isolément en premier, compilez d'abord shared une fois :

npm run build:shared

7. (Optionnel) Un intercepteur SMTP pour consulter les emails

TimePick envoie des emails (magic links, invitations, notifications). En développement, si aucun serveur SMTP n'est configuré dans server/.env, l'application envoie automatiquement vers 127.0.0.1:1025 — tout intercepteur SMTP local écoutant sur ce port convient (Mailpit, MailCatcher, MailDev…), sans configuration supplémentaire pour tester le flux d'authentification par email. Les exemples ci-dessous utilisent Mailpit, l'outil exercé sur l'instance de référence.

Installer et démarrer Mailpit via Homebrew :

brew install mailpit

brew services start mailpit

Ou via Docker :

docker run -p 1025:1025 -p 8025:8025 axllent/mailpit

Les emails interceptés sont consultables dans l'interface web : http://localhost:8025

Ou, sans rien installer, via le fichier compose.dev.yaml fourni à la racine du dépôt :

npm run mail

npm run mail démarre Mailpit et attend que son healthcheck intégré soit vert (--wait). Interface web : http://localhost:8025. Pour arrêter le conteneur : npm run mail:stop.

TIP

Ce service est opt-in : il ne démarre que via son profil mail, jamais avec npm run dev. Il requiert Docker et Docker Compose v2 (le drapeau up --wait utilisé par npm run mail existe depuis Compose v2.1.1 ; voir Prérequis). Si les ports 1025/8025 sont déjà pris par un binding IPv4 (typiquement docker run -p 1025:1025 …), npm run mail échoue avec port is already allocated — c'est attendu : conservez dans ce cas votre intercepteur existant sans activer le profil. Sur macOS, un Mailpit Homebrew écoute en IPv6 et peut coexister avec le service compose (lié en IPv4 loopback).

8. Vérifier l'installation

Ouvrez http://localhost:5173 dans votre navigateur : l'application doit se charger (elle vous redirigera vers l'assistant de configuration initiale si aucun administrateur n'existe encore).

Vérifiez que l'API répond :

curl http://localhost:3000/health

La réponse doit être un code HTTP 200 avec un corps JSON indiquant l'état du serveur.

Votre instance locale est maintenant opérationnelle. Passez à Configuration initiale pour créer le premier compte administrateur via l'assistant /setup.

9. (Optionnel) Lancer les tests en local

Une fois le dépôt cloné et une instance PostgreSQL locale démarrée (voir Prérequis), npm test fonctionne sans configuration supplémentaire : le harness de tests (server/src/__tests__/helpers/test-db-config.js) applique des valeurs par défaut sûres (base timepick_test, identifiants postgres/postgres, port 5432) dès que server/.env.test est absent.

cd server
npm test

Le harness crée automatiquement les bases timepick_test et timepick_test_migrations (dédiée aux tests de migrations), puis les supprime/recrée à chaque run via globalSetup.

Privilège CREATEDB requis

L'utilisateur PostgreSQL utilisé pour les tests doit posséder le privilège CREATEDB :

psql -c "ALTER USER postgres CREATEDB"

Sur certaines installations PostgreSQL anciennes, l'extension uuid-ossp peut nécessiter un rôle superutilisateur (psql -c "ALTER USER postgres SUPERUSER"), ou une pré-installation de l'extension dans template1 par un administrateur.

Surcharger la configuration de test (identifiants PostgreSQL non standard)

server/.env.test n'est nécessaire que si vos identifiants PostgreSQL locaux diffèrent des valeurs par défaut. Dans ce cas, créez server/.env.test en n'y mettant que les clés à surcharger — le plus souvent une seule ligne :

echo 'DATABASE_URL=postgresql://mon_user:mon_mdp@localhost:5432/timepick_test' > server/.env.test

TIP

server/.env.test est un fichier local, non committé (.gitignore). Toute variable qui y est définie prend le pas sur le défaut du harness ; les variables absentes conservent leur valeur par défaut. Le nom de la base doit rester timepick_test : le garde-fou assertTestDbUrl refuse toute autre cible.

Variable optionnelle supplémentaire : TEST_DB_VERBOSE=1 journalise le détail du bootstrap des bases de test (silencieux par défaut).