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:
parent
53f3af9794
commit
5b37d09fa9
592
docs/ARCHITECTURE_TECHNIQUE.md
Normal file
592
docs/ARCHITECTURE_TECHNIQUE.md
Normal 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.
|
||||
Loading…
x
Reference in New Issue
Block a user