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	secret généré (voir ci-dessous)
ENCRYPTION_KEY	Clé de chiffrement (mots de passe SMTP stockés en base)	secret généré, 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.

Générez deux secrets forts, un par commande :

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) MailHog pour intercepter 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 bascule automatiquement sur MailHog à l'adresse 127.0.0.1:1025 — aucune configuration supplémentaire n'est nécessaire pour tester le flux d'authentification par email.

Installer et démarrer MailHog via Homebrew :

brew install mailhog

mailhog

Ou via Docker :

docker run -p 1025:1025 -p 8025:8025 mailhog/mailhog

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

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.