Migration depuis CSWeb Vanilla Guide de migration de CSWeb vanilla vers CSWeb Community Platform v2.0.

Compatibilité

Avant de Commencer

Évaluation

Prérequis

• Accès root serveur CSWeb vanilla
• Backup complet de la base MySQL
• Serveur destination avec Docker installé
• Temps de downtime accepté (1-4h selon volume)

Procédure de Migration

Étape 1: Backup CSWeb Vanilla

# Sur serveur CSWeb vanilla
 
# 1. Backup base MySQL metadata
mysqldump -u root -p csweb_metadata > backup_vanilla_metadata.sql
 
# 2. Backup fichiers uploadés
tar -czf backup_vanilla_files.tar.gz /var/www/html/files/
 
# 3. Copier vers serveur destination
scp backup_vanilla_metadata.sql user@new-server:/tmp/
scp backup_vanilla_files.tar.gz user@new-server:/tmp/

Étape 2: Installer CSWeb Community

# Sur nouveau serveur
 
# Clone repository
git clone https://github.com/BOUNADRAME/csweb-community.git
cd csweb-community
 
# Installation
./install.sh
# Choisir: PostgreSQL (pour breakout)

Étape 3: Restore Metadata

# Arrêter containers
docker compose down
 
# Restore MySQL metadata
docker compose up -d mysql
sleep 10 # Attendre démarrage MySQL docker compose exec -T mysql mysql -u root -p csweb_metadata < /tmp/backup_vanilla_metadata.sql
 
# Vérifier
docker compose exec mysql mysql -u root -p csweb_metadata SHOW TABLES; # Doit afficher tables CSPro
SELECT COUNT(*) FROM cspro_dictionaries;

Étape 4: Restore Fichiers

# Extraire fichiers
tar -xzf /tmp/backup_vanilla_files.tar.gz -C files/
 
# Corriger permissions
docker compose exec csweb chown -R www-data:www-data /var/www/html/files

Étape 5: Redémarrer CSWeb Community

# Démarrer stack complète
docker compose --profile local-postgres up -d
 
# Vérifier
docker compose ps
docker compose logs csweb

Étape 6: Vérification

Accéder à CSWeb : http://new-server:8080 (opens in a new tab)

Vérifier :

• Login admin fonctionne (même credentials vanilla)
• Dictionnaires visibles (Administration Dictionaries)
• Utilisateurs visibles (Administration Users)
• Fichiers accessibles

Étape 7: Breakout Sélectif (Nouveau)

# Lister dictionnaires
docker compose exec mysql mysql -u csweb_user -p csweb_metadata SELECT name, label FROM cspro_dictionaries;
 
# Breakout vers PostgreSQL
docker compose exec csweb php bin/console csweb:process-cases-by-dict \
 dictionnaires=SURVEY_DICT,CENSUS_DICT \
 --threads=5 \
 -vvv

Résultat : Tables PostgreSQL créées (survey_cases, census_cases, etc.)

Étape 8: Tests Fonctionnels

• Upload nouveau questionnaire
• Synchronisation fonctionne
• API OAuth fonctionne
• Breakout sélectif fonctionne
• Requêtes SQL sur PostgreSQL fonctionnent

Migration Scénarios

Scénario 1: Migration Simple (< 100k questionnaires)

Temps estimé : 1-2 heures

1. Backup vanilla
2. Installer CSWeb Community
3. Restore metadata + fichiers
4. Breakout sélectif
5. Tests

Scénario 2: Migration RGPH (Millions de questionnaires)

Temps estimé : 4-8 heures (+ temps breakout)

Particularités :

• Planifier downtime (weekend/nuit)
• Augmenter threads breakout (10+)
• Utiliser SQL Server distant si disponible
• Backup incrémentaux pendant migration

Exemple RGPH5 Sénégal :

# Migration metadata: 30 min
# Breakout gros volume: gain significatif avec threads (SQL Server)
# Total downtime: 7h

Scénario 3: Migration Progressive (Coexistence temporaire)

Configuration :

• CSWeb vanilla : Production (lecture seule)
• CSWeb Community : Test/validation (nouveau breakout)
• Basculement après validation complète

Rollback (Retour Vanilla)

Si Migration Échoue

# 1. Arrêter CSWeb Community
docker compose down
 
# 2. Restaurer CSWeb vanilla depuis backup
# (sur ancien serveur ou nouveau)
 
mysqldump < backup_vanilla_metadata.sql
tar -xzf backup_vanilla_files.tar.gz
 
# 3. Redémarrer CSWeb vanilla
service apache2 restart

Perte de données : Uniquement données créées après backup (avant migration).

Migration Inverse (Community Vanilla)

Possible mais déconseillé.

Que garder :

• Base MySQL metadata (100% compatible)
• Fichiers uploadés
• Utilisateurs, dictionnaires, OAuth clients

Que perdre :

• Tables breakout PostgreSQL/SQL Server
• Breakout sélectif (revenir au global)
• Architecture flexible

Procédure :

1. Backup MySQL metadata depuis Community
2. Restore sur CSWeb vanilla
3. Re-breakout global vanilla

FAQ Migration

Les données vanilla sont-elles modifiées ?

Non. CSWeb Community lit la base metadata vanilla sans modification structurelle.

Puis-je tester sans affecter la production ?

Oui. Clone vanilla sur serveur test, puis migre le clone.

Combien de temps de downtime ?

Inclut : Backup + migration + breakout + tests.

Les URLs API changent-elles ?

Non. API 100% compatible :

• POST /api/token
• GET /api/dictionaries
• GET /api/files/media/{filename}/content

Les clients OAuth existants fonctionnent-ils ?

Oui. Table cspro_oauth_clients préservée.

Support Migration

Besoin d'aide pour migration ?

1. Documentation : Getting Started
2. GitHub Issues : https://github.com/BOUNADRAME/csweb-community/issues (opens in a new tab)
3. Email : Voir profil GitHub

Ressources

• Installation : Getting Started - Installation
• Breakout Sélectif : Guides - Breakout Sélectif
• Backup : Deployment - Backup & Restore
• Troubleshooting : Common Issues

CSWeb Community Platform v2.0 - Migration Guide Architecte : Bouna DRAME | Portfolio (opens in a new tab)