From 5b37d09fa98cc1a5a23ff028ecf3a1ca45fd39a1 Mon Sep 17 00:00:00 2001 From: Julien Martin Date: Tue, 27 Jan 2026 16:29:44 +0100 Subject: [PATCH] =?UTF-8?q?[Doc]=20Guide=20d'architecture=20technique=20et?= =?UTF-8?q?=20d=C3=A9ploiement=20(#61=20#16)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- docs/ARCHITECTURE_TECHNIQUE.md | 592 +++++++++++++++++++++++++++++++++ 1 file changed, 592 insertions(+) create mode 100644 docs/ARCHITECTURE_TECHNIQUE.md diff --git a/docs/ARCHITECTURE_TECHNIQUE.md b/docs/ARCHITECTURE_TECHNIQUE.md new file mode 100644 index 0000000..5fead37 --- /dev/null +++ b/docs/ARCHITECTURE_TECHNIQUE.md @@ -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. \ No newline at end of file