Skip to content

0.run-local-env.md

Latest commit

 

History

History
266 lines (183 loc) · 5.61 KB

0.run-local-env.md

File metadata and controls

266 lines (183 loc) · 5.61 KB

Installation Backend + PostgreSQL

🎯 Objectif

Démarrer un environnement de développement avec PostgreSQL en Docker et le backend DomiFa.

🔧 Prérequis

  • Node.js >= 24
  • pnpm >= 10 (via corepack recommandé) 
    corepack enable
corepack prepare pnpm@10.24.0 --activate

🐳 Modes de développement

Mode hybride (recommandé)

PostgreSQL en Docker + Backend en local avec pnpm workspaces – permet un meilleur contrôle du développement.

Mode Docker complet

Tous les services dans Docker – utile pour la reproductibilité mais moins flexible pour le développement.

⚙️ Configuration des variables d'environnement

Fichiers requis (obligatoires)

# 1. Configuration racine
cp .env.dev.example.env .env

# 2. Configuration backend
cp packages/backend/.env.backend.dev.example.env packages/backend/.env

# 3. Configuration tests (optionnel)
cp packages/backend/.env.backend.test.local.example.env packages/backend/.env.backend.test.local.env

Configuration de la connexion PostgreSQL

Mode Docker complet (Backend aussi en Docker) :

# Dans packages/backend/.env
POSTGRES_HOST=postgres
# OU utiliser le preset
DOMIFA_ENV_PRESET=local-dev-docker.preset.env

Mode hybride (Backend en local, PostgreSQL en Docker) :

# Dans packages/backend/.env
POSTGRES_HOST=localhost
# OU utiliser le preset
DOMIFA_ENV_PRESET=local-dev.preset.env

🏗️ Build des dépendances communes

⚠️ ÉTAPE OBLIGATOIRE – Le package @domifa/common doit être compilé avant de démarrer les autres projets :

# À la racine du projet
pnpm --filter @domifa/common build

# OU avec l'alias (voir section Alias)
domcom build

🐳 Lancement de l'environnement Docker

Démarrage des services

# PostgreSQL uniquement (recommandé avec pnpm workspaces)
./docker-compose.local.run.sh

# PostgreSQL + Backend en Docker (mode conteneurisé)
./docker-compose.local.run.sh --with-dev-containers

Gestion des containers

# Arrêter les services
./docker-compose.local.run.sh --stop

# Supprimer les containers
./docker-compose.local.run.sh --stop --remove

# Reset complet (⚠️ SUPPRIME TOUTES LES DONNÉES DOMIFA)
./docker-compose.local.run.sh --stop --remove --drop-domifa-volumes

🗄️ Base de données PostgreSQL

Initialisation automatique

Les bases de données sont créées automatiquement au premier démarrage avec des données de test.

📖 Voir ./2.databases-dumps.md pour plus de détails

Vérification

# Vérifier que PostgreSQL fonctionne
docker ps | grep postgres
docker logs domifa-postgres

🚀 Démarrage du Backend

Mode hybride avec pnpm workspaces (recommandé)

# À la racine du projet – démarre le backend via le workspace
pnpm --filter @domifa/backend start:dev

# OU directement dans le dossier backend
cd packages/backend
pnpm start:dev

# OU avec l'alias (voir section Alias)
back start:dev

Mode Docker complet

# Entrer dans le container backend
docker exec -it domifa-backend bash

# Dans le container
pnpm start:dev

🎯 Pourquoi des hooks Git ?

  • lint-staged : Formatage et linting automatique des fichiers modifiés
  • node-talisman : Détection de secrets/credentials avant commit
  • lerna : Gestion du monorepo et des workspaces

🔧 Installation

# Lerna (déjà dans devDependencies du projet)
npx lerna --version || pnpm add -D lerna

# Husky
npx husky init

✅ Vérification de l'installation

ls -la .husky/
# Doit afficher : pre-commit, commit-msg
npx lerna --version
# Doit afficher la version installée

🔧 Alias Zsh pour un développement plus rapide

Ajoutez ces alias dans votre ~/.zshrc pour accélérer vos commandes :

# Alias pour les workspaces DomiFa (pnpm)

alias front='pnpm --filter @domifa/frontend'
alias back='pnpm --filter @domifa/backend'
alias portail='pnpm --filter @domifa/portail-usagers'
alias admin='pnpm --filter @domifa/portail-admins'
alias domcom='pnpm --filter @domifa/common'

Exemples d'utilisation :

# Build le package common
domcom build

# Démarrer le backend
back start:dev

# Démarrer le frontend
front start

# Lancer les tests backend
back test

🔧 Commandes utiles

# Voir les logs PostgreSQL
docker logs domifa-postgres -f

# Voir les logs Backend (si en Docker)
docker logs domifa-backend -f

# Reset uniquement la base de données
docker volume rm domifa_postgres_data

# Migrations manuelles
pnpm --filter @domifa/backend db:dev:migrate-up
pnpm --filter @domifa/backend db:dev:create -- NomDeLaMigration

🚨 Dépannage

PostgreSQL ne démarre pas

# Vérifier les logs
docker logs domifa-postgres

# Vérifier l'espace disque
df -h

# Nettoyer les volumes orphelins
docker volume prune

Backend ne se connecte pas à PostgreSQL

# Vérifier la configuration
cat packages/backend/.env | grep POSTGRES

# Vérifier que PostgreSQL accepte les connexions
telnet localhost 5432

Port 3000 déjà utilisé

# Identifier le processus
lsof -i :3000
kill -9 <PID>

Modules manquants

# Réinstaller les dépendances backend
cd packages/backend
pnpm install --frozen-lockfile

Erreur de build du package common

# Nettoyer et rebuilder (exemple, selon vos scripts npm)
pnpm --filter @domifa/common build

🎯 Résultat attendu

À la fin de cette installation, vous devez avoir :

  • ✅ Package @domifa/common compilé
  • ✅ PostgreSQL accessible sur localhost:5432
  • ✅ Backend API accessible sur http://localhost:3000