Guides
Architecture & Déploiement
Architecture & Déploiement

Architecture & Déploiement

CSWeb Community Platform v2.0 offre une architecture flexible qui vous permet de choisir votre base de données et votre mode de déploiement selon vos besoins.

Vue d'Ensemble

L'architecture flexible vous permet de :

  • Choisir votre SGBD : PostgreSQL (recommandé), MySQL ou SQL Server
  • Déployer localement : Docker Compose pour développement/tests
  • Déployer en production : Serveurs distants pour RGPH et recensements
  • Migrer à chaud : Changer de SGBD sans réinstaller CSWeb

Concept Clé : Deux Bases de Données

CSWeb utilise toujours 2 bases distinctes :

1. MySQL Metadata (Obligatoire - Non Modifiable)

  • Stocke les utilisateurs, dictionnaires, tokens OAuth
  • Schéma imposé par CSWeb vanilla (compatibilité bidirectionnelle)
  • Doit être MySQL (compatibilité CSWeb vanilla)

2. Base Breakout (Configurable)

  • Stocke les données "breakées" (cas, niveaux, notes)
  • Structure définie par vos dictionnaires CSPro
  • Peut être PostgreSQL, MySQL ou SQL Server
  • Optimisée pour analyses statistiques
┌─────────────────────┐      ┌────────────────────────┐
│  MySQL Metadata     │      │  Breakout Database     │
│  (Fixe)             │      │  (Flexible)            │
├─────────────────────┤      ├────────────────────────┤
│ • Users             │      │ • {dict}_cases         │
│ • Dictionaries      │      │ • {dict}_notes         │
│ • OAuth Tokens      │      │ • {dict}_level_1       │
│ • Sync Queue        │      │ • {dict}_level_2       │
└─────────────────────┘      └────────────────────────┘
   CSWeb vanilla           PostgreSQL/MySQL/SQL Server

Mode LOCAL (Docker)

Tous les services (CSWeb + MySQL metadata + Base breakout) tournent sur la même machine.

Quand Utiliser

  • Développement et tests
  • POC (Proof of Concept) et démos
  • Formation CSWeb
  • Petits volumes (< 50k questionnaires)

Architecture Docker

┌──────────────── Docker Compose Stack ────────────────┐
│                                                       │
│  ┌──────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  CSWeb   │  │ csweb-mysql  │  │  postgres    │  │
│  │  :8080   │  │    :3306     │  │   :5432      │  │
│  │ (Apache) │  │  (Metadata)  │  │ (Breakout)   │  │
│  └──────────┘  └──────────────┘  └──────────────┘  │
│                                                       │
│          Réseau: csweb_network                       │
└───────────────────────────────────────────────────────┘

Configuration

Fichier .env (PostgreSQL) :

# Mode déploiement
DEPLOYMENT_MODE=local
BREAKOUT_DB_TYPE=postgresql
 
# PostgreSQL (Container Docker)
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DATABASE=csweb_analytics
POSTGRES_USER=csweb_analytics
POSTGRES_PASSWORD=secure_pass
 
# MySQL Metadata (Container Docker - Fixe)
MYSQL_HOST=csweb-mysql
MYSQL_PORT=3306
MYSQL_DATABASE=csweb
MYSQL_USER=csweb
MYSQL_PASSWORD=metadata_pass

Lancement

# Lancer tous les containers
docker compose --profile local-postgres up -d
 
# Vérifier les services
docker compose ps
 
# Tester les drivers
docker compose exec csweb php bin/console csweb:check-database-drivers

Mode REMOTE (Production)

CSWeb tourne localement mais se connecte à des serveurs de bases de données distants.

Quand Utiliser

  • Production avec gros volumes (> 100k questionnaires)
  • Recensements nationaux (RGPH)
  • Infrastructure existante à réutiliser
  • Haute disponibilité requise

Architecture Remote

┌─────────── Host Machine ───────────┐
│                                    │
│  ┌──────────┐                      │
│  │  CSWeb   │                      │
│  │  :8080   │                      │
│  │(Container)│                     │
│  └────┬─────┘                      │
│       │                            │
└───────┼────────────────────────────┘
        │
        │ VPN/LAN
        │
┌───────▼──── Production Network ────┐
│                                     │
│ ┌─────────────┐  ┌───────────────┐│
│ │ MySQL       │  │ PostgreSQL    ││
│ │192.168.1.50 │  │192.168.1.100  ││
│ │  :3306      │  │   :5432       ││
│ │ (Metadata)  │  │ (Breakout)    ││
│ └─────────────┘  └───────────────┘│
└─────────────────────────────────────┘

Prérequis

  1. Connectivité réseau : VPN, LAN ou Internet
  2. Ports ouverts : MySQL (3306), PostgreSQL (5432), SQL Server (1433)
  3. Firewall configuré sur serveurs distants
  4. SGBD configuré pour accepter connexions externes

Configuration

Fichier .env (Remote PostgreSQL) :

# Mode déploiement
DEPLOYMENT_MODE=remote
BREAKOUT_DB_TYPE=postgresql
 
# PostgreSQL REMOTE
POSTGRES_HOST=192.168.1.100
POSTGRES_PORT=5432
POSTGRES_DATABASE=prod_analytics
POSTGRES_USER=analytics_user
POSTGRES_PASSWORD=ProdSecurePass123!
 
# MySQL Metadata REMOTE
MYSQL_HOST=192.168.1.50
MYSQL_PORT=3306
MYSQL_DATABASE=csweb_prod
MYSQL_USER=csweb_prod
MYSQL_PASSWORD=MetadataSecurePass!

Lancement

# Seul le container CSWeb démarre (pas de containers DB)
docker compose up -d
 
# Vérifier connexion aux serveurs distants
docker compose exec csweb php bin/console csweb:check-database-drivers --test-connections

Output attendu :

✓ MySQL Metadata : Connected to 192.168.1.50:3306/csweb_prod
✓ PostgreSQL Breakout : Connected to 192.168.1.100:5432/prod_analytics

Comparaison LOCAL vs REMOTE

CritèreLOCAL (Docker)REMOTE (Production)
Complexité setupFacile (1 commande)Moyenne (config réseau/firewall)
PerformancesRapide (réseau interne)Dépend du réseau
ScalabilitéLocale (1 machine)Élevée (serveurs dédiés)
CoûtGratuitServeurs + licenses
Use caseDev/Test/POCProduction/RGPH
Volume recommandé< 50k cas> 100k cas

Choisir Votre SGBD

PostgreSQL (Recommandé)

Avantages :

  • Performances excellentes pour analytics
  • Types de données avancés (JSON, arrays)
  • Requêtes complexes optimisées
  • Open source et gratuit

Quand choisir :

  • Volume > 100k questionnaires
  • Analyses statistiques avancées
  • Solution open source (sans licenses commerciales)

MySQL

Avantages :

  • Compatible avec CSWeb vanilla
  • Écosystème mature
  • Migration facile depuis vanilla

Quand choisir :

  • Migration depuis CSWeb vanilla existant
  • Équipe déjà formée MySQL
  • Volume < 100k questionnaires

SQL Server

Avantages :

  • Intégration Microsoft (Power BI, Azure)
  • Outils d'administration avancés
  • Support entreprise

Quand choisir :

  • Infrastructure Microsoft existante
  • Budget pour licenses
  • Besoin d'intégration Power BI

Migration À Chaud

Vous pouvez changer de SGBD sans réinstaller CSWeb.

Étapes

1. Backup des Données

# PostgreSQL
docker compose exec postgres pg_dump -U csweb_analytics csweb_analytics > backup.sql
 
# MySQL
docker compose exec mysql-breakout mysqldump -u breakout_user -p csweb_breakout > backup.sql

2. Modifier .env

# Avant
BREAKOUT_DB_TYPE=postgresql
POSTGRES_HOST=postgres
 
# Après
BREAKOUT_DB_TYPE=mysql
MYSQL_BREAKOUT_HOST=mysql-breakout
MYSQL_BREAKOUT_PORT=3307

3. Relancer Containers

# Arrêter ancien profil
docker compose --profile local-postgres down
 
# Démarrer nouveau profil
docker compose --profile local-mysql up -d

4. Re-Breakout

# Recommandé : re-breakout complet
docker compose exec csweb php bin/console csweb:process-cases-by-dict eval --overwrite

Cas d'Usage Réel : RGPH5 Sénégal

Contexte :

  • ANSD (Agence Nationale de la Statistique et de la Démographie)
  • Plusieurs millions de questionnaires RGPH5
  • Serveur SQL Server existant

Configuration :

DEPLOYMENT_MODE=remote
BREAKOUT_DB_TYPE=sqlserver
 
# SQL Server REMOTE (ANSD)
SQLSERVER_HOST=172.16.0.50
SQLSERVER_PORT=1433
SQLSERVER_DATABASE=RGPH5_Analytics
SQLSERVER_USER=sa
SQLSERVER_PASSWORD=RGPH5SecurePass!

Résultat :

  • Gain de temps significatif grâce au breakout sélectif (vs mode global)
  • Données stockées sur SQL Server de production
  • Analyses SQL directes sur serveur ANSD

Drivers Pré-Installés

Tous les drivers sont pré-installés dans le container CSWeb :

docker compose exec csweb php bin/console csweb:check-database-drivers

Output attendu :

✓ pdo_mysql : Available (MySQL metadata + breakout)
✓ pdo_pgsql : Available (PostgreSQL breakout)
✓ pdo_sqlsrv : Available (SQL Server breakout)
DriverSGBDUsageExtension PHP
pdo_mysqlMySQL/MariaDBMetadata + Breakoutext-pdo_mysql
pdo_pgsqlPostgreSQLBreakout uniquementext-pdo_pgsql
pdo_sqlsrvSQL ServerBreakout uniquementext-pdo_sqlsrv + ODBC Driver 18

Troubleshooting

Cannot connect to remote database

Symptôme :

Connection refused: 192.168.1.100:5432

Solutions :

  1. Vérifier réseau :
ping 192.168.1.100
telnet 192.168.1.100 5432
  1. Vérifier firewall :
sudo ufw allow 5432/tcp
  1. Vérifier configuration PostgreSQL :
# postgresql.conf
listen_addresses = '*'
 
# pg_hba.conf
host all all 0.0.0.0/0 md5

Port already in use

Symptôme :

Error: port 5432 is already allocated

Solution :

# Arrêter PostgreSQL local
sudo systemctl stop postgresql
 
# Ou changer port Docker
POSTGRES_PORT=5433

Authentication failed

Symptôme :

SQLSTATE[28000]: Invalid authorization specification

Solutions :

  1. PostgreSQL : Vérifier pg_hba.conf utilise md5 (pas peer)
  2. MySQL : Créer user avec wildcard :
CREATE USER 'user'@'%' IDENTIFIED BY 'password';
GRANT ALL ON database.* TO 'user'@'%';

Commandes Utiles

Vérifier Configuration Active

# Variables breakout
docker compose exec csweb env | grep BREAKOUT
 
# Variables PostgreSQL
docker compose exec csweb env | grep POSTGRES

Tester Connexions

docker compose exec csweb php bin/console csweb:check-database-drivers --test-connections

Changer Mode à Chaud

# 1. Modifier .env
nano .env
 
# 2. Redémarrer CSWeb
docker compose restart csweb
 
# 3. Vérifier
docker compose exec csweb php bin/console csweb:check-database-drivers

Ressources

Architecture par Bouna DRAME | Portfolio (opens in a new tab) | GitHub (opens in a new tab)

Prochaines ÉtapesTransformation PostgreSQL