Guide d'installation et de configuration

Ce guide s'adresse à l'administrateur plateforme (rôle ADMIN). Il couvre l'installation sur VPS, la configuration des variables d'environnement, le premier démarrage et la gestion opérationnelle.

Checklist de démarrage

Avant de lancer l'environnement, vérifier que les points suivants sont couverts :

[ ] Node.js 20 LTS installé sur le VPS
[ ] Docker Engine 24+ et Docker Compose v2 installés
[ ] PostgreSQL 16 accessible (ou démarré via Docker)
[ ] Domaines DNS configurés et pointant sur le VPS
[ ] Fichiers .env créés dans api/, app/, et backoffice/
[ ] JWT_SECRET généré et renseigné (obligatoire)
[ ] Certificats TLS gérés par Traefik (Let's Encrypt)
[ ] Après le premier démarrage : configurer Agents IA, Stockage S3 et Stripe depuis Backoffice → Paramètres

Prérequis

Composant	Version minimale
Node.js	20 LTS
PostgreSQL	14+ (16 recommandé)
Docker Engine	24+
Docker Compose	v2+
Domaines DNS	`api`, `app`, `bo` + sous-domaines dev

Les trois packages (api/, app/, backoffice/) sont indépendants. Chacun a son propre package.json et son propre .env.

Structure des environnements

Branche git	VPS	URLs
`dev`	Dev	`api-dev.governia.eu` · `app-dev.governia.eu` · `bo-dev.governia.eu`
`main`	Prod	`api.governia.eu` · `app.governia.eu` · `bo.governia.eu`

1. Variables d'environnement

`api/.env`

env

# Base de données
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=governia
DATABASE_PASSWORD=<mot_de_passe_fort>
DATABASE_NAME=governia_prod

# Auth — REQUIS : l'API refuse de démarrer sans JWT_SECRET
JWT_SECRET=<générer avec : openssl rand -base64 64>
JWT_EXPIRES_IN=7d

# Frontend (redirections OAuth, emails)
APP_FRONTEND_URL=https://app.governia.eu
BO_FRONTEND_URL=https://bo.governia.eu

# Env
NODE_ENV=production
PORT=4000
PUPPETEER_CACHE_DIR=/root/.cache/puppeteer

JWT_SECRET : générer avec openssl rand -base64 64. Ne jamais committer cette valeur. La changer invalide toutes les sessions actives.

Agents IA, Stockage S3, Stripe : à configurer depuis Backoffice → Paramètres après le premier démarrage. L'API démarre sans elles — les fonctionnalités sont simplement désactivées jusqu'à la configuration.

`app/.env`

env

NEXT_PUBLIC_API_URL=https://api.governia.eu
APP_NODE_ENV=production

⚠️ Sur VPS : toujours définir APP_NODE_ENV=production. Le mode dev (Turbopack) consomme ~1.5 GB de RAM et sature le CPU lors des compilations à la demande.

`backoffice/.env`

env

NEXT_PUBLIC_API_URL=https://api.governia.eu

2. Démarrage Docker (VPS)

bash

# Cloner le dépôt
git clone https://github.com/nashvilleboy2019-art/governia.git
cd governia

# Créer les fichiers .env
cp api/.env.example api/.env   # puis éditer avec vos valeurs
echo "NEXT_PUBLIC_API_URL=https://api.governia.eu" > app/.env
echo "NEXT_PUBLIC_API_URL=https://api.governia.eu" > backoffice/.env

# Lancer en production
docker compose -f docker-compose.prod.yml up -d

# Vérifier les logs de l'API
docker compose -f docker-compose.prod.yml logs -f api --tail=50

Noms des services Docker

Service	Rôle	Port interne
`db`	PostgreSQL 16	5432
`api`	NestJS backend	4000
`client`	App Next.js (portail client)	3000
`backoffice`	Backoffice Next.js	3000
`docs`	VitePress documentation	5173

Note : le portail client est nommé client dans Docker, pas app.

Vérifier que tout tourne

bash

# Statut des containers
docker compose -f docker-compose.prod.yml ps

# Santé de l'API
curl https://api.governia.eu/health

# Logs en temps réel
docker compose -f docker-compose.prod.yml logs -f api --tail=100

3. Workflow de déploiement

  Développement local
         │
         ▼
    branche dev  ──push──►  VPS dev  (git pull + restart)
         │
         ▼
    PR dev → main
         │
         ▼
    branche main ──push──►  VPS prod (git pull + restart)

Mise à jour sur le VPS prod

bash

git pull origin main

# Rebuild API
docker compose -f docker-compose.prod.yml up -d --build api

# Rebuild Backoffice
docker compose -f docker-compose.prod.yml up -d --build backoffice

# App client — vider le cache Next.js avant rebuild
docker volume rm app_next_cache bo_next_cache
docker compose -f docker-compose.prod.yml up -d

Volumes cache Next.js

Les caches .next sont persistés dans des volumes nommés. Si les changements ne semblent pas pris en compte après un git pull :

bash

docker compose -f docker-compose.prod.yml stop client
docker compose -f docker-compose.prod.yml run --rm client sh -c "rm -rf /usr/src/app/.next"
docker compose -f docker-compose.prod.yml up -d client

4. Base de données

Première initialisation

TypeORM crée les tables automatiquement au premier démarrage de l'API (via synchronize: true en dev, migrations explicites en prod).

Pour créer la base manuellement :

bash

psql -U postgres -c "CREATE DATABASE governia_prod;"
psql -U postgres -c "CREATE USER governia WITH PASSWORD 'xxxx';"
psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE governia_prod TO governia;"

Sauvegarde

bash

# Export
docker exec governia_prod_db pg_dump -U postgres governia_prod > backup_$(date +%Y%m%d).sql

# Restore
docker exec -i governia_prod_db psql -U postgres governia_prod < backup_20250101.sql

5. Gestion des tenants et utilisateurs

Depuis le backoffice (bo.governia.eu) :

Créer un nouveau client ou cabinet

Utilisateurs → Créer une société — saisir raison sociale, type (CLIENT ou CABINET), contact principal
Un tenant est créé automatiquement avec l'organisation
Inviter le premier utilisateur : Invitations → Créer une invitation → rôle MANAGER_BU + tenant

Rôles disponibles

Rôle	Interface	Périmètre
`ADMIN`	Backoffice	Accès complet plateforme
`MANAGER_BU`	App	Gestion du cabinet, missions, utilisateurs
`AUDITOR`	App	Conduite des audits, questionnaires, rapports
`RESP_CLIENT`	App	Gestion des actions de remédiation, consultation
`OPERATOR`	App	Consultation en lecture

Flux d'invitation

Backoffice → Invitations → Créer
Saisir l'email, choisir le rôle et le tenant
Copier le lien d'acceptation et l'envoyer manuellement
L'utilisateur clique, définit son mot de passe, est redirigé vers l'app

L'envoi d'email automatique est en cours d'intégration.

6. Monitoring et supervision

Page Monitoring (backoffice)

Le backoffice expose une page Monitoring (/monitoring) avec :

Statut des services (API, base de données, stockage S3, agents IA)
Métriques de consommation IA par tenant
Historique des connexions utilisateur
Volume d'audits et de recommandations

Dashboard backoffice

La page d'accueil (/) affiche en temps réel :

Latences : PostgreSQL, Back-office, App client, Stockage S3
Alertes billing : abonnements en retard, essais expirant, résiliations planifiées

Commandes de supervision

bash

# Santé de l'API
curl https://api.governia.eu/health

# Logs en temps réel
docker compose -f docker-compose.prod.yml logs -f api --tail=100

# Métriques de ressources
docker stats

7. Sécurité

Point	Configuration
JWT	Durée par défaut 7 jours. Rotation recommandée tous les 90 jours — changer `JWT_SECRET` invalide toutes les sessions
Passwords	Hashés avec bcrypt (coût 10). Aucun mot de passe en clair en base
S3	Preuves stockées sous `evidences/{env}/{tenantId}/{auditId}/...` — isolation par tenant
Multi-tenancy	Le header `X-Tenant-Id` est vérifié contre le JWT. Impossible d'accéder aux données d'un autre tenant
Ports exposés	Seuls 80/443 (Traefik) doivent être ouverts. PostgreSQL ne doit pas être accessible depuis Internet
Backoffice	Protégé par basic auth Traefik en plus du JWT

8. Intégrations tierces

Intégration	Guide
Agents IA	/integrations/agents-ia
Stockage S3	/integrations/stockage-s3
Stripe	/integrations/stripe
Jira	/integrations/jira
Puppeteer PDF	/integrations/puppeteer

9. Dépannage

L'API ne démarre pas

Symptôme	Cause	Solution
`JWT_SECRET is required`	Variable manquante	Ajouter `JWT_SECRET` dans `api/.env`
`ECONNREFUSED 5432`	PostgreSQL non démarré	Démarrer le service `db` en premier
`Cannot connect to database`	Mauvaises credentials	Vérifier `DATABASE_*` dans `api/.env`
`Chrome not found`	Puppeteer non installé	L'API installe Chrome au démarrage — attendre la fin du build

Les modifications ne s'affichent pas (Next.js)

bash

# Vider le cache Next.js
docker volume rm app_next_cache bo_next_cache
docker compose -f docker-compose.prod.yml up -d

Le token Jira est expiré

Si le bouton → Jira retourne une erreur :

Suite → Paramètres → Intégrations
Cliquer Reconnecter — le flow OAuth renouvelle le token

Les fonctions IA ou le stockage S3 ne fonctionnent pas

Vérifier que les intégrations sont configurées dans Backoffice → Paramètres → Agents IA / Stockage S3. Si le quota du provider est dépassé, ajuster dans les paramètres ou changer de provider.

Guide d'installation et de configuration ​

Checklist de démarrage ​

Prérequis ​

Structure des environnements ​

1. Variables d'environnement ​

api/.env ​

app/.env ​

backoffice/.env ​

2. Démarrage Docker (VPS) ​

Noms des services Docker ​

Vérifier que tout tourne ​

3. Workflow de déploiement ​

Mise à jour sur le VPS prod ​

Volumes cache Next.js ​

4. Base de données ​

Première initialisation ​

Sauvegarde ​

5. Gestion des tenants et utilisateurs ​

Créer un nouveau client ou cabinet ​

Rôles disponibles ​

Flux d'invitation ​

6. Monitoring et supervision ​

Page Monitoring (backoffice) ​

Dashboard backoffice ​

Commandes de supervision ​

7. Sécurité ​

8. Intégrations tierces ​

9. Dépannage ​

L'API ne démarre pas ​

Les modifications ne s'affichent pas (Next.js) ​

Le token Jira est expiré ​

Les fonctions IA ou le stockage S3 ne fonctionnent pas ​

Guide d'installation et de configuration

Checklist de démarrage

Prérequis

Structure des environnements

1. Variables d'environnement

`api/.env`

`app/.env`

`backoffice/.env`

2. Démarrage Docker (VPS)

Noms des services Docker

Vérifier que tout tourne

3. Workflow de déploiement

Mise à jour sur le VPS prod

Volumes cache Next.js

4. Base de données

Première initialisation

Sauvegarde

5. Gestion des tenants et utilisateurs

Créer un nouveau client ou cabinet

Rôles disponibles

Flux d'invitation

6. Monitoring et supervision

Page Monitoring (backoffice)

Dashboard backoffice

Commandes de supervision

7. Sécurité

8. Intégrations tierces

9. Dépannage

L'API ne démarre pas

Les modifications ne s'affichent pas (Next.js)

Le token Jira est expiré

Les fonctions IA ou le stockage S3 ne fonctionnent pas