Aller au contenu

Guide de Setup - ProbatioVault Backend

Prérequis

Logiciels requis

  • Node.js : 20.x LTS ou supérieur
  • npm : 10.x ou supérieur
  • PostgreSQL : 15+ (ou Docker)
  • Redis : 7+ (ou Docker)
  • Git : 2.x
  • Docker (optionnel) : 24+
  • Docker Compose (optionnel) : 2.x

Vérification des versions

node -v    # v20.x.x
npm -v     # 10.x.x
git --version
psql --version  # PostgreSQL 15+
redis-cli --version  # 7.x

Installation

1. Cloner le projet

git clone https://gitlab.com/probatiovault/probatiovault-backend.git
cd probatiovault-backend

2. Installer les dépendances

npm install

Cette commande installe : - Toutes les dépendances de production - Toutes les devDependencies - Les pre-commit hooks (si configurés)

Durée estimée : 2-3 minutes

3. Configuration de l'environnement

a. Copier le fichier d'environnement

cp .env.example .env.development

b. Éditer .env.development

# Application
NODE_ENV=development
PORT=3000

# Database (PostgreSQL)
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=probatio
DATABASE_PASSWORD=votre_mot_de_passe_secure
DATABASE_NAME=probatiovault_dev

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

# JWT
JWT_SECRET=votre_secret_jwt_tres_long_et_aleatoire
JWT_EXPIRATION=1h
JWT_REFRESH_EXPIRATION=7d

# Bcrypt
BCRYPT_SALT_ROUNDS=12

# CORS
CORS_ORIGIN=http://localhost:3000

# Storage S3 (OVH)
S3_ENDPOINT=https://s3.gra.io.cloud.ovh.net
S3_REGION=gra
S3_ACCESS_KEY_ID=votre_access_key
S3_SECRET_ACCESS_KEY=votre_secret_key
S3_BUCKET=probatiovault-documents-dev

# AWS Glacier (optionnel)
GLACIER_ENABLED=false
GLACIER_REGION=us-east-1
GLACIER_VAULT_NAME=probatiovault-archive-dev

⚠️ Important : Ne jamais committer le fichier .env.development !

4. Base de données PostgreSQL

Option A : Docker (recommandé)

docker-compose up -d postgres

Option B : Installation locale

# Installation PostgreSQL 15 (macOS)
brew install postgresql@15
brew services start postgresql@15

# Création de la base de données
createdb probatiovault_dev

# Connexion
psql probatiovault_dev

5. Redis

Option A : Docker (recommandé)

docker-compose up -d redis

Option B : Installation locale

# Installation Redis (macOS)
brew install redis
brew services start redis

# Vérification
redis-cli ping  # Devrait retourner PONG

6. Exécuter les migrations

npm run migrate

Cette commande crée toutes les tables nécessaires.

7. (Optionnel) Peupler la base avec des données de test

npm run seed

Lancer l'application

Mode développement (hot-reload)

npm run start:dev

L'API est accessible sur : - API : http://localhost:3000 - Swagger : http://localhost:3000/api/docs - Health : http://localhost:3000/health

Mode production

npm run build
npm run start:prod

Mode debug

npm run start:debug

Ensuite, attachez votre debugger sur le port 9229.

Utilisation avec Docker Compose

Lancer la stack complète

docker-compose up -d

Cette commande lance : - API NestJS (port 3000) - PostgreSQL (port 5432) - Redis (port 6379) - pgAdmin (port 5050)

Accès aux services

  • API : http://localhost:3000
  • pgAdmin : http://localhost:5050
  • Email : admin@probatiovault.com
  • Password : admin

Commandes utiles

# Voir les logs
docker-compose logs -f api

# Arrêter la stack
docker-compose down

# Rebuild l'image
docker-compose build api

# Redémarrer un service
docker-compose restart api

Vérification de l'installation

1. Health check

curl http://localhost:3000/health

Résultat attendu : 

{
  "status": "ok",
  "timestamp": "2025-01-13T..."
}

2. Lancer les tests

npm run test

Tous les tests doivent passer ✅

3. Vérifier la compilation TypeScript

npm run build

Aucune erreur de compilation attendue.

4. Vérifier le linting

npm run lint:check

Aucune erreur ESLint attendue.

Configuration IDE

Visual Studio Code

Extensions recommandées

Créer .vscode/extensions.json :

{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "ms-vscode.vscode-typescript-next",
    "firsttris.vscode-jest-runner",
    "42crunch.vscode-openapi"
  ]
}

Settings recommandés

Créer .vscode/settings.json :

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "jest.autoRun": "off"
}

WebStorm / IntelliJ IDEA

  1. Activer ESLint : Settings > Languages & Frameworks > JavaScript > Code Quality Tools > ESLint
  2. Activer Prettier : Settings > Languages & Frameworks > JavaScript > Prettier
  3. Format on save : Settings > Tools > Actions on Save

Troubleshooting

Erreur : "Cannot find module"

# Nettoyer et réinstaller
rm -rf node_modules package-lock.json
npm install

Erreur : "Port 3000 already in use"

# Trouver le processus
lsof -i :3000

# Tuer le processus
kill -9 <PID>

# Ou changer le port dans .env
PORT=3001

Erreur : "Connection refused" PostgreSQL

# Vérifier que PostgreSQL tourne
brew services list  # macOS
systemctl status postgresql  # Linux

# Relancer PostgreSQL
brew services restart postgresql@15

Erreur : "Redis connection failed"

# Vérifier que Redis tourne
redis-cli ping

# Relancer Redis
brew services restart redis

Erreur : "Migration failed"

# Vérifier la connexion BDD
psql probatiovault_dev

# Rollback si nécessaire
npm run migrate:revert

# Relancer
npm run migrate

Prochaines étapes

Une fois le setup terminé :

  1. Consulter Swagger : http://localhost:3000/api/docs
  2. Lire le Guide de contribution
  3. Explorer l'Architecture

Support

En cas de problème :

  1. Vérifier les Issues connues
  2. Demander de l'aide sur Slack : #probatiovault-backend
  3. Créer une issue : Nouvelle issue

Bon développement ! 🚀