FAQ (Foire Aux Questions)

Réponses aux 30+ questions les plus fréquentes sur CSWeb Community Platform v2.0.

Général

Qu'est-ce que CSWeb Community Platform ?

CSWeb Community Platform v2.0 est une extension open-source de CSWeb (Census and Survey Processing System) développée par Bouna DRAME.

Améliorations par rapport à CSWeb vanilla :

• Architecture flexible : Support PostgreSQL, MySQL, SQL Server
• Breakout sélectif : Par dictionnaire (innovation Assietou DIAGNE)
• Déploiement Docker : Installation en 5 minutes
• Multi-database : 2 bases distinctes (metadata + analytics)
• Local & Remote : Développement local ou serveurs distants
• Production-ready : Validé en production lors du RGPH5 Sénégal

Quelle est la différence avec CSWeb vanilla ?

Est-ce gratuit / open-source ?

Oui, 100% gratuit et open-source.

• Licence : MIT License (permissive)
• Code source : GitHub - csweb-community (opens in a new tab)
• Contributions : Bienvenues (pull requests, issues)

Coûts éventuels :

• Infrastructure serveur (si production cloud)
• Licences SQL Server (si choix SQL Server en production)
• PostgreSQL et MySQL sont gratuits

Puis-je migrer de CSWeb vanilla vers CSWeb Community ?

Oui, migration bidirectionnelle possible.

De vanilla vers Community :

1. Backup base MySQL vanilla
2. Installer CSWeb Community (Docker)
3. Restaurer backup dans container mysql (metadata)
4. Lancer breakout sélectif vers PostgreSQL/MySQL/SQL Server
5. Données analytiques séparées, metadata intacte

De Community vers vanilla :

• Base MySQL metadata compatible 100%
• Backup metadata restaurer sur CSWeb vanilla
• Perte du breakout sélectif (revenir au breakout global)

Installation

Quels sont les prérequis ?

Matériel :

• CPU : 2 cores minimum (4+ recommandés)
• RAM : 4 GB minimum (8+ recommandés)
• Disque : 10 GB minimum (+ espace données)

Logiciels :

• Docker Engine 20.10+
• Docker Compose 2.0+
• Git (pour cloner repository)

Système d'exploitation :

• Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+)
• macOS 11+ (Big Sur+)
• Windows 10+ avec WSL2

L'installation prend combien de temps ?

Installation complète : 5-10 minutes

Détails :

1. Clone repository : ~1 min
2. Lancement install.sh : ~30 secondes
3. Pull images Docker : ~3-5 min (selon connexion)
4. Setup.php (interface) : ~2 min
5. Premier breakout test : ~1 min

Total : 5-10 minutes pour installation production-ready.

Peut-on installer sans Docker ?

Oui, mais déconseillé.

Installation manuelle (sans Docker) :

• Installer PHP 8.1+ avec extensions (pdo_mysql, pdo_pgsql, pdo_sqlsrv)
• Installer MySQL 8.0+ pour metadata
• Installer PostgreSQL/MySQL/SQL Server pour breakout
• Configurer Apache/Nginx
• Configurer permissions
• Installer dépendances Composer

Temps estimé : 2-3 heures (vs 5 minutes avec Docker)

Documentation : Voir docs/INSTALLATION-CSWEB-VANILLA.md (non recommandé).

Comment désinstaller complètement ?

# Arrêter et supprimer containers
docker compose down -v # -v = supprimer volumes
 
# Supprimer images
docker rmi $(docker images 'pg_csweb8*' -q)
 
# Supprimer dossier projet
cd ..
rm -rf csweb-community
 
# (Optionnel) Nettoyer Docker
docker system prune -a

Base de Données

Pourquoi 2 bases de données distinctes ?

Raisons techniques :

1. Base MySQL Metadata (FIXE)

• Schéma imposé par CSWeb vanilla
• Compatibilité bidirectionnelle garantie
• Petit volume (< 100 MB)
• Performances suffisantes

2. Base Breakout (FLEXIBLE)

• Structure dynamique (définie par dictionnaires CSPro)
• Gros volumes (millions de lignes)
• Besoin performances analytics (PostgreSQL)
• Indépendance des releases CSWeb vanilla

Avantage : Choisir le meilleur SGBD pour chaque usage.

Quel SGBD choisir pour le breakout ?

Recommandations :

Benchmark performances (50k cas) :

• PostgreSQL : ~45 min (5 threads)
• MySQL : ~50 min (5 threads)
• SQL Server : ~42 min (5 threads)

Différence négligeable. Choisir selon infrastructure/expertise.

Peut-on changer de SGBD après installation ?

Oui, migration à chaud possible.

Procédure :

1. Modifier .env : BREAKOUT_DB_TYPE=mysql postgresql
2. Arrêter container ancien SGBD
3. Démarrer container nouveau SGBD
4. Re-breakout des dictionnaires

Temps estimé : 30 min (+ temps re-breakout selon volume).

Documentation : Architecture - Flexible

La base metadata DOIT-elle être MySQL ?

Oui, actuellement.

Raison : Schéma metadata imposé par CSWeb vanilla (compatibility layer).

Possible future évolution :

• PostgreSQL metadata (perte compatibilité vanilla)
• Contributions bienvenues pour implémenter

Workaround actuel : MySQL metadata + PostgreSQL breakout (hybrid mode).

Breakout Sélectif

Qu'est-ce que le breakout sélectif ?

Définition : Processus de transformation de questionnaires CSPro en tables SQL par dictionnaire, au lieu d'un breakout global.

Innovation : Développé par Assietou DIAGNE (ANSD, Sénégal).

Avantages :

• Isolation : Tables séparées par dictionnaire (eval_cases, kairos_cases)
• Performance : Traitement parallèle, pas de contention
• Flexibilité : Breakout uniquement les dictionnaires nécessaires
• Scalabilité : Validé en production lors du RGPH5 Sénégal avec un gain de temps significatif

Pattern de nommage :

{label}_{table_name}

Exemples:
- EVAL_DICT eval_cases, eval_producteurs
- KAIROS_DICT kairos_cases, kairos_observations

Quelle est la différence entre breakout global et sélectif ?

Combien de temps prend un breakout ?

Dépend de :

• Nombre de questionnaires
• Complexité dictionnaires (levels, records)
• Nombre de threads
• Performances serveur

Benchmarks :

Le temps de breakout dépend du volume de données, du matériel et du driver SGBD. Le breakout sélectif (par dictionnaire) est significativement plus rapide que le breakout global car il traite un seul dictionnaire à la fois.

Facteurs principaux : nombre de cas, complexité du dictionnaire (niveaux, items), performances disque et réseau.

Peut-on annuler un breakout en cours ?

Oui.

# Trouver processus
docker compose exec csweb ps aux | grep process-cases
 
# Tuer processus (remplacer PID)
docker compose exec csweb kill -9 <PID>
 
# Ou Ctrl+C si lancé en foreground

Conséquence : Tables partiellement remplies.

Nettoyage :

# Relancer avec --overwrite pour écraser
docker compose exec csweb php bin/console csweb:process-cases-by-dict \
 dictionnaires=EVAL_DICT \
 --overwrite

Déploiement

Peut-on déployer en production ?

Oui, production-ready.

Validations :

• RGPH5 Sénégal : Validé en production (ANSD)
• Gambie, Guinée : Recensements nationaux
• Autres INS africains : En cours de déploiement

Recommandations production :

• Serveur dédié (4+ CPU, 16+ GB RAM)
• Backups automatisés (daily)
• Monitoring (Prometheus, Grafana)
• VPN pour accès distant
• SSL/TLS (Let's Encrypt)

Comment déployer sur serveur distant ?

Étapes :

1. Sur serveur distant :

# Installer Docker
curl -fsSL https://get.docker.com | sh
 
# Cloner repository
git clone https://github.com/BOUNADRAME/csweb-community.git
cd csweb-community
 
# Lancer installation
./install.sh

2. Configurer .env (remote mode) :

BREAKOUT_MODE=remote
BREAKOUT_DB_TYPE=sqlserver # Exemple RGPH5
 
# SQL Server distant
SQLSERVER_HOST=172.16.0.50
SQLSERVER_PORT=1433
SQLSERVER_DATABASE=RGPH5_Analytics
SQLSERVER_USER=sa
SQLSERVER_PASSWORD=SecurePass!

3. Démarrer :

docker compose up -d

Accès :

http://<IP_SERVEUR>:8080

Comment sécuriser l'accès en production ?

1. Reverse Proxy (Nginx + SSL) :

server {
 listen 443 ssl;
 server_name csweb.example.org;
 
 ssl_certificate /etc/letsencrypt/live/csweb.example.org/fullchain.pem;
 ssl_certificate_key /etc/letsencrypt/live/csweb.example.org/privkey.pem;
 
 location / {
 proxy_pass http://localhost:8080;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 }
}

2. Firewall :

# Bloquer accès direct port 8080
sudo ufw deny 8080/tcp
 
# Autoriser HTTPS uniquement
sudo ufw allow 443/tcp

3. VPN :

• OpenVPN ou WireGuard
• Accès réservé aux IPs autorisées

4. Authentification forte :

• Mots de passe complexes (16+ caractères)
• JWT expiration courte (1h)
• Refresh tokens sécurisés

Performance

Comment optimiser les performances du breakout ?

1. Augmenter les threads :

# Optimal : Nb_CPU - 1
--threads=7 # Si serveur 8 CPU

2. Augmenter mémoire PHP :

php -d memory_limit=2G bin/console csweb:process-cases-by-dict ...

3. Désactiver logs debug :

# .env
CSWEB_PROCESS_CASES_LOG_LEVEL=error

4. Indexes (PostgreSQL) :

CREATE INDEX idx_eval_cases_guid ON eval_cases(guid);
CREATE INDEX idx_eval_prod_parent ON eval_producteurs(parent_guid);

5. Partitionnement (gros volumes) :

-- PostgreSQL 12+ : Partition par range (date)
CREATE TABLE eval_cases (
 guid VARCHAR(255),
 modified_date TIMESTAMP
) PARTITION BY RANGE (modified_date);
 
CREATE TABLE eval_cases_2025 PARTITION OF eval_cases
FOR VALUES FROM ('2025-01-01') TO ('2026-01-01');

Gain potentiel : 2-3x plus rapide avec optimisations complètes.

Le breakout consomme combien de RAM ?

Estimation :

La consommation RAM dépend du volume de données traité. Plus le nombre de cas est élevé, plus la RAM nécessaire augmente.

Recommandations serveur :

• Petit volume : 4 GB RAM minimum
• Volume moyen : 8 GB RAM recommandé
• Gros volume : 16+ GB RAM

Sécurité

Les mots de passe sont-ils stockés en clair ?

Non, jamais.

CSWeb utilise :

• Hachage bcrypt (password_hash() PHP)
• Salt automatique (unique par mot de passe)
• Coût 10 (par défaut, augmente temps brute-force)

Exemple :

// Mot de passe: "SecurePass123!"
// Stocké en DB:
$2y$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy

Impossible de récupérer le mot de passe original (hachage unidirectionnel).

Comment changer le mot de passe admin ?

Via Interface Web :

1. Login CSWeb (admin / admin123 par défaut)
2. Administration Users Edit admin
3. Changer password
4. Sauvegarder

Via MySQL Direct :

# Se connecter à MySQL metadata
docker compose exec mysql mysql -u csweb -p csweb
 
# Générer hash
# (Utiliser https://bcrypt-generator.com/ ou PHP)

UPDATE cspro_users
SET password = '$2y$10$NEW_HASH_HERE'
WHERE username = 'admin';

Support & Contributions

Comment obtenir de l'aide ?

1. Documentation :

• Getting Started
• Guides - Breakout Sélectif
• Troubleshooting

2. GitHub Issues :

• https://github.com/BOUNADRAME/csweb-community/issues (opens in a new tab)
• Créer issue avec :
• Description problème
• Logs (docker compose logs > debug.log)
• Configuration (.env sans mots de passe)

3. Community :

• Discord (lien dans README)
• Email : Voir profil GitHub

Comment contribuer au projet ?

Contributions bienvenues !

Types de contributions :

• Bug fixes
• Nouvelles fonctionnalités
• Documentation
• Traductions (EN, FR, ES, PT)
• Tests

Procédure :

1. Fork repository
2. Créer branche : feature/ma-fonctionnalite
3. Commit changements
4. Push vers fork
5. Créer Pull Request

Guidelines : Voir CONTRIBUTING.md (racine projet).

Qui maintient le projet ?

Lead Developer : Bouna DRAME (opens in a new tab)

• GitHub : @BOUNADRAME (opens in a new tab)
• Portfolio : bounadrame.github.io (opens in a new tab)

Contributeurs clés :

• Assietou DIAGNE (ANSD, Sénégal) : Breakout sélectif, Transformation CSWeb PostgreSQL
• Community contributors : Voir Contributors

Licences & Légal

Quelle est la licence du projet ?

MIT License (permissive).

Vous pouvez :

• Utiliser commercialement
• Modifier le code
• Distribuer
• Sublicencier

Conditions :

• Inclure copyright notice
• Inclure copie de la licence

Garantie : AUCUNE (AS IS).

Texte complet : Voir LICENSE (racine projet).

Puis-je utiliser pour un projet commercial ?

Oui, absolument.

Exemples d'usage commercial :

• Institut national de statistique (INS)
• Cabinet de conseil en statistiques
• Entreprise SaaS (offrir CSWeb as a Service)
• Formation payante

Obligation : Inclure copyright notice (respect MIT License).

Recommandé : Mentionner CSWeb Community Platform + contribuer améliorations.

Cas d'Usage Réels

Qui utilise CSWeb Community Platform ?

Validations production :

1. ANSD Sénégal (Agence Nationale de la Statistique et de la Démographie)

• RGPH5 (Recensement Général de la Population et de l'Habitat)
• Plusieurs millions de questionnaires
• SQL Server breakout
• Gain de temps significatif vs CSWeb vanilla

2. Gambie

• Census national
• PostgreSQL breakout

3. Guinée

• Recensement national
• SQL Server breakout

4. Autres INS africains (en cours)

Le RGPH5 Sénégal a vraiment utilisé cette plateforme ?

Oui, validation production RGPH5 Sénégal 2025.

Chiffres :

• Plusieurs millions de questionnaires
• 10 threads parallèles
• SQL Server 2019 (serveur ANSD)
• Fraction du temps de breakout vs mode global
• Gain de performance significatif vs breakout global

Innovation : Breakout sélectif par dictionnaire (Assietou DIAGNE, ANSD).

Documentation : Voir Breakout Sélectif.

Autres Questions

Peut-on importer des données existantes ?

Oui, plusieurs méthodes :

1. Import CSV :

-- PostgreSQL
COPY eval_producteurs FROM '/path/data.csv' CSV HEADER;
 
-- MySQL
LOAD DATA INFILE '/path/data.csv'
INTO TABLE eval_producteurs
FIELDS TERMINATED BY ','
ENCLOSED BY '"'
LINES TERMINATED BY '\n'
IGNORE 1 ROWS;

2. Import depuis autre DB :

# PostgreSQL
pg_dump -h old_server -U user source_db | psql -h localhost -U csweb_analytics csweb_analytics

3. Re-breakout depuis CSPro :

• Upload dictionnaires CSPro
• Upload questionnaires (.dat)
• Lancer csweb:process-cases-by-dict

Comment faire un backup complet ?

Backup automatisé (recommandé) :

#!/bin/bash
# backup.sh - Backup quotidien DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backups/csweb/$DATE"
mkdir -p $BACKUP_DIR
 
# 1. Backup MySQL metadata
docker compose exec mysql mysqldump -u csweb -p csweb > $BACKUP_DIR/metadata.sql
 
# 2. Backup PostgreSQL breakout
docker compose exec postgres pg_dump -U csweb_analytics csweb_analytics > $BACKUP_DIR/analytics.sql
 
# 3. Backup fichiers
tar -czf $BACKUP_DIR/files.tar.gz ./files
 
# 4. Backup .env
cp .env $BACKUP_DIR/.env.backup echo "Backup completed: $BACKUP_DIR"

Cron daily :

# crontab -e
0 2 * * * /path/to/backup.sh

La documentation est-elle à jour ?

Oui, documentation synchronisée avec le code.

Dernière mise à jour : 15 Mars 2026

Version documentée : CSWeb Community Platform v2.0.0

Comment vérifier :

# Version du code
git log -1 --format="%H %ci"
 
# Version de la documentation
cat docs-nextra/package.json | grep version

Contributions : Pull requests bienvenues pour améliorer docs !

Vous n'avez pas trouvé votre réponse ?

1. Troubleshooting : Common Issues
2. GitHub Issues : Créer une issue (opens in a new tab)
3. Discord : Lien dans README
4. Email : Voir profil GitHub

CSWeb Community Platform v2.0 - FAQ Lead Developer : Bouna DRAME | Breakout Sélectif : Assietou DIAGNE