jmartin/petitspas
1
0
Fork 0
Code Issues 36 Pull Requests Actions Packages Projects Releases Wiki Activity

[Doc] Guide d'architecture technique et déploiement (#61 #16)

Browse Source 
Ajout d'une documentation technique complète pour l'infrastructure
et le déploiement de l'application P'titsPas.

Contenu du guide :
- Vue d'ensemble de l'architecture (Flutter frontend + Node.js backend)
- Prérequis serveur (Node.js, PostgreSQL, ressources recommandées)
- Instructions d'installation pas à pas
- Configuration de la base de données PostgreSQL
- Déploiement du backend (NestJS)
- Build et déploiement du frontend Flutter Web
- Configuration NGINX comme reverse proxy
- Sécurisation SSL/TLS avec Let's Encrypt
- Monitoring et maintenance
- Sauvegarde et restauration
- Troubleshooting des problèmes courants

Ce document est essentiel pour le déploiement on-premise de l'application
par les collectivités locales.

Refs: #61 (Guide installation & configuration), #16 (Doc config on-premise)
This commit is contained in:
MARTIN Julien 2026-01-27 16:29:44 +01:00
parent 53f3af9794
commit 5b37d09fa9
1 changed files with 592 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

592
docs/ARCHITECTURE_TECHNIQUE.md Normal file
View File

@ -0,0 +1,592 @@
# Architecture Technique - P'titsPas
## Guide d'Infrastructure et de Déploiement
---
## Vue d'ensemble
P'titsPas est une application de gestion de garde d'enfants pour les collectivités locales, basée sur une architecture **client-serveur moderne** :
- **Frontend** : Application web Flutter (Single Page Application)
- **Backend** : API REST Node.js/Express avec TypeScript
- **Base de données** : PostgreSQL avec ORM Prisma
- **Architecture** : Séparation claire frontend/backend avec API REST
---
## Prérequis Serveur
### Environnement d'exécution
#### Backend
- **Node.js** : Version 18+ (LTS recommandée : 18.19.0+)
- **npm** : Version 9+
- **TypeScript** : Inclus dans les dépendances du projet
#### Base de données
- **PostgreSQL** : Version 15+
- **Extensions** : UUID (pour les clés primaires)
#### Frontend
- **Serveur web statique** : nginx, Apache, ou similaire
- **Flutter Web** : Compilation en JavaScript (pas de prérequis runtime)
### Ressources recommandées
#### Environnement de développement
- **RAM** : 4GB minimum
- **CPU** : 2 vCPU
- **Storage** : 10GB
#### Environnement de production
- **RAM** : 8GB recommandé (4GB minimum)
- **CPU** : 4 vCPU recommandé (2 vCPU minimum)
- **Storage** : 50GB minimum (base de données + logs + backups)
- **Réseau** :
- Port 3000 : API Backend (interne)
- Port 80/443 : Web (externe)
- Port 5432 : PostgreSQL (interne uniquement)
---
## Stack Technique Détaillée
### Backend (API)
```json
{
"runtime": "Node.js 18+",
"language": "TypeScript",
"framework": "Express.js 4.18+",
"orm": "Prisma 6.7+",
"database_client": "@prisma/client",
"security": [
"helmet (sécurité headers)",
"cors (CORS policy)",
"bcrypt (hashage mots de passe)",
"jsonwebtoken (JWT auth)"
],
"logging": "morgan",
"validation": "@nestjs/common"
}
```
### Frontend (Web)
```json
{
"framework": "Flutter 3.2.6+",
"language": "Dart 3.0+",
"compilation": "JavaScript (Flutter Web)",
"navigation": "go_router 13.2+",
"state_management": "provider 6.1+",
"ui_framework": "Material Design",
"fonts": "Google Fonts",
"http_client": "http 1.2+"
}
```
### Base de données
```sql
-- Structure PostgreSQL
-- Tables principales :
-- - Parent (utilisateurs parents)
-- - Child (enfants)
-- - Contract (contrats de garde)
-- - Admin (administrateurs)
-- - Theme (thèmes interface)
-- - AppSettings (paramètres app)
-- Types de données :
-- - UUID pour toutes les clés primaires
-- - Timestamps automatiques (createdAt, updatedAt)
-- - Enums pour les statuts
```
---
## Installation et Configuration
### 1. Prérequis système
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install -y nodejs npm postgresql postgresql-contrib nginx
# Vérification versions
node --version # >= 18.0.0
npm --version # >= 9.0.0
psql --version # >= 15.0
```
### 2. Configuration base de données
```sql
-- Se connecter en tant que postgres
sudo -u postgres psql
-- Créer la base de données et l'utilisateur
CREATE DATABASE ptitspas;
CREATE USER ptitspas_user WITH PASSWORD 'secure_password_here';
GRANT ALL PRIVILEGES ON DATABASE ptitspas TO ptitspas_user;
ALTER USER ptitspas_user CREATEDB; -- Pour les migrations
-- Quitter
\q
```
### 3. Installation Backend
```bash
cd backend
# Installation des dépendances
npm install
# Configuration environnement
cp .env.example .env
# Éditer .env avec vos paramètres
# Génération du client Prisma et migrations
npx prisma generate
npx prisma migrate deploy
# Initialisation admin (optionnel)
npm run init-admin
```
### 4. Installation Frontend
```bash
cd frontend
# Installation des dépendances Flutter
flutter pub get
# Build pour production
flutter build web --release
```
---
## Variables d'Environnement
### Backend (.env)
```bash
# Base de données
DATABASE_URL="postgresql://ptitspas_user:secure_password_here@localhost:5432/ptitspas"
# Sécurité
JWT_SECRET="your-super-secret-jwt-key-minimum-32-characters"
JWT_EXPIRES_IN="24h"
# Serveur
PORT=3000
NODE_ENV=production
# Optionnel
CORS_ORIGIN="https://ptitspas.yourdomain.com"
```
---
## Déploiement
### Option 1 : Déploiement classique (recommandé)
#### Backend
```bash
cd backend
# Installation production
npm ci --only=production
# Build TypeScript
npm run build
# Démarrage (avec PM2 recommandé)
npm install -g pm2
pm2 start dist/index.js --name "ptitspas-api"
pm2 startup
pm2 save
```
#### Frontend
```bash
cd frontend
# Build production
flutter build web --release
# Copier vers serveur web
sudo cp -r build/web/* /var/www/ptitspas/
sudo chown -R www-data:www-data /var/www/ptitspas/
```
### Option 2 : Conteneurisation Docker
#### Dockerfile Backend
```dockerfile
FROM node:18-alpine
# Créer répertoire app
WORKDIR /app
# Copier package files
COPY package*.json ./
COPY prisma ./prisma/
# Installer dépendances
RUN npm ci --only=production
# Copier code source
COPY . .
# Build
RUN npm run build
# Générer client Prisma
RUN npx prisma generate
# Exposer port
EXPOSE 3000
# Variables d'environnement
ENV NODE_ENV=production
# Commande démarrage
CMD ["npm", "start"]
```
#### Dockerfile Frontend
```dockerfile
FROM nginx:alpine
# Copier build Flutter
COPY build/web /usr/share/nginx/html
# Configuration nginx
COPY nginx.conf /etc/nginx/nginx.conf
# Exposer port
EXPOSE 80
# Démarrage nginx
CMD ["nginx", "-g", "daemon off;"]
```
#### Docker Compose
```yaml
version: '3.8'
services:
postgres:
image: postgres:15-alpine
environment:
POSTGRES_DB: ptitspas
POSTGRES_USER: ptitspas_user
POSTGRES_PASSWORD: secure_password_here
volumes:
- postgres_data:/var/lib/postgresql/data
ports:
- "5432:5432"
backend:
build: ./backend
environment:
DATABASE_URL: postgresql://ptitspas_user:secure_password_here@postgres:5432/ptitspas
JWT_SECRET: your-super-secret-jwt-key
NODE_ENV: production
ports:
- "3000:3000"
depends_on:
- postgres
frontend:
build: ./frontend
ports:
- "80:80"
depends_on:
- backend
volumes:
postgres_data:
```
---
## Configuration Nginx
### Configuration complète
```nginx
server {
listen 80;
server_name ptitspas.yourdomain.com;
# Redirection HTTPS
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name ptitspas.yourdomain.com;
# Certificats SSL
ssl_certificate /etc/letsencrypt/live/ptitspas.yourdomain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/ptitspas.yourdomain.com/privkey.pem;
# Configuration SSL sécurisée
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off;
# Frontend statique (Flutter Web)
location / {
root /var/www/ptitspas;
index index.html;
try_files $uri $uri/ /index.html;
# Cache statique
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
}
# API Backend
location /api/ {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_bypass $http_upgrade;
# Timeouts
proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
}
# Logs
access_log /var/log/nginx/ptitspas_access.log;
error_log /var/log/nginx/ptitspas_error.log;
}
```
---
## Sécurité
### Obligatoire
1. **HTTPS avec certificat SSL**
```bash
# Installation Certbot
sudo apt install certbot python3-certbot-nginx
# Génération certificat
sudo certbot --nginx -d ptitspas.yourdomain.com
# Renouvellement automatique
sudo crontab -e
# Ajouter : 0 12 * * * /usr/bin/certbot renew --quiet
```
2. **Firewall**
```bash
# UFW (Ubuntu)
sudo ufw allow 22 # SSH
sudo ufw allow 80 # HTTP
sudo ufw allow 443 # HTTPS
sudo ufw enable
```
3. **Base de données sécurisée**
```bash
# PostgreSQL : accès local uniquement
sudo nano /etc/postgresql/15/main/postgresql.conf
# Commenter : #listen_addresses = 'localhost'
sudo nano /etc/postgresql/15/main/pg_hba.conf
# Vérifier que seules les connexions locales sont autorisées
```
4. **Backup automatique**
```bash
# Script backup
#!/bin/bash
BACKUP_DIR="/var/backups/ptitspas"
DATE=$(date +%Y%m%d_%H%M%S)
pg_dump -U ptitspas_user -h localhost ptitspas > $BACKUP_DIR/ptitspas_$DATE.sql
# Nettoyer les backups > 30 jours
find $BACKUP_DIR -name "*.sql" -mtime +30 -delete
# Crontab : tous les jours à 2h
# 0 2 * * * /path/to/backup_script.sh
```
### Recommandé
1. **Fail2Ban** (protection brute force)
```bash
sudo apt install fail2ban
sudo systemctl enable fail2ban
```
2. **Monitoring des logs**
```bash
# Logrotate pour éviter les gros fichiers
sudo nano /etc/logrotate.d/ptitspas
```
3. **Updates automatiques**
```bash
sudo apt install unattended-upgrades
sudo dpkg-reconfigure unattended-upgrades
```
---
## Commandes de Gestion
### Démarrage des services
```bash
# Backend (développement)
cd backend && npm run dev
# Backend (production avec PM2)
pm2 start ptitspas-api
pm2 status
# Base de données
sudo systemctl start postgresql
sudo systemctl status postgresql
# Serveur web
sudo systemctl start nginx
sudo systemctl status nginx
```
### Maintenance
```bash
# Migrations base de données
cd backend
npx prisma migrate deploy
# Logs Backend
pm2 logs ptitspas-api
# Logs Nginx
sudo tail -f /var/log/nginx/ptitspas_access.log
sudo tail -f /var/log/nginx/ptitspas_error.log
# Restart services
pm2 restart ptitspas-api
sudo systemctl restart nginx
```
---
## Monitoring et Healthcheck
### Endpoints de santé
```bash
# API Health (à implémenter)
curl https://ptitspas.yourdomain.com/api/health
# Base de données
psql -h localhost -U ptitspas_user -d ptitspas -c "SELECT 1;"
# Frontend
curl -I https://ptitspas.yourdomain.com/
```
### Logs à surveiller
1. **Backend** : Via PM2 ou logs applicatifs
2. **PostgreSQL** : `/var/log/postgresql/postgresql-15-main.log`
3. **Nginx** : `/var/log/nginx/ptitspas_*.log`
4. **Système** : `/var/log/syslog`
### Métriques importantes
- **CPU/RAM** : Usage serveur
- **Espace disque** : Base de données et logs
- **Connexions DB** : Nombre de connexions actives
- **Temps de réponse** : API et frontend
- **Erreurs 5xx** : Erreurs serveur
---
## Troubleshooting
### Problèmes courants
1. **Backend ne démarre pas**
```bash
# Vérifier variables d'environnement
cd backend && cat .env
# Vérifier connexion DB
npx prisma db pull
# Logs détaillés
npm run dev
```
2. **Frontend ne s'affiche pas**
```bash
# Vérifier build
cd frontend && flutter build web
# Vérifier nginx
sudo nginx -t
sudo systemctl reload nginx
```
3. **Erreurs base de données**
```bash
# Vérifier statut PostgreSQL
sudo systemctl status postgresql
# Vérifier connexions
sudo -u postgres psql -c "SELECT * FROM pg_stat_activity;"
```
---
## Évolutivité
### Optimisations possibles
1. **Cache Redis** : Pour les sessions et cache applicatif
2. **CDN** : Pour les assets statiques
3. **Load Balancer** : Pour haute disponibilité
4. **Clustering** : Multiple instances Node.js
5. **Database replication** : Master/Slave PostgreSQL
### Monitoring avancé
- **Prometheus + Grafana** : Métriques système et applicatif
- **ELK Stack** : Centralisation des logs
- **Uptime monitoring** : Surveillance externe
Cette architecture est conçue pour être **scalable**, **maintenable** et **sécurisée** pour un environnement de production professionnel.