Migrateur

Lorsque l’on est amené à reproduire plusieurs fois la migration d’un même site, il peut être intéressant d’en écrire un scénario, et de pouvoir le rejouer à volonté sans oublier aucune étape. Le migrateur a été conçu pour cela, et permet des migrations de sites de SPIP 2 vers SPIP 2, de SPIP 2 vers SPIP 3 et de SPIP 3 vers SPIP 3.

Qu’est ce que Migrateur ?

Migrateur est un plugin pour SPIP 2 ou SPIP 3 qui permet de réaliser sous forme de scripts des migrations complexes et répétitives, telles qu’on en rencontre dans le cadre des refontes de sites, entre un site en cours de production et un site en cours de développement. Le plugin Migrateur est à utiliser si l’on veut travailler sur le site de développement quasiment en temps réel avec les données du site de production, et même si les deux serveurs sont dans deux versions de SPIP différentes [1].

Que fait Migrateur ?

Migrateur propose par défaut 3 fonctions souvent utilisées lors d’une migration, à savoir :
-  la synchro du dossier IMG
-  le dump de la base de production
-  la remontée de cette base vers le site de production

Ces fonctions seront exécutées par le migrateur selon la configuration stockée dans le fichier config.php contenu dans le dossier plugins/migrateur/. Ce fichier peut être surchargé dans le dossier squelettes/ (créer un dossier squelettes/migrateur/ et placez-y le fichier config.php), ou bien avec un nouveau mini-plugin que vous créerez à cet usage.

Le plugin de surcharge sera composé d’un fichier paquet.xml nécessitant Migrateur :

<paquet
	prefix="migrateur_xxxx"
	categorie="outils"
	version="1.0.0"
	schema="1.0.0"
	etat="dev"
	compatibilite="[3.0.0;3.0.*]"
>
	<nom>Migrateur XXXX</nom>
	<necessite nom="migrateur" compatibilite="[2.5.0;]" />
</paquet>

et d’un dossier migrateur/ contenant le fichier config.php).

Mais le Migrateur ne s’arrête pas à ces 3 fonctions de base ! Il peut exécuter de nombreuses autres fonctions de migration, telles que le changement de nom de site et d’url, l’activation de plugins supplémentaires, le positionnement de méta-données (ajout / suppression de spip_metas), la translation de données, etc. Ces fonctions seront définies dans un fichier de fonctions, puis appelées dans le fichier de config de la même manière que les 3 fonctions de base. Voir en fin d’article de nombreux exemples de fonctions de migration.

Dans quel cas utiliser Migrateur ?

Le plugin Migrateur a donc été conçu pour faciliter le « scriptage » de migrations répétitives et/ou nécessitant de nombreuses actions post-migration. Il s’adresse plutôt à un public de développeurs, bien que son exécution puisse être réalisée depuis l’interface privée. Du fait que la mise au point des étapes de migration puisse nécessiter un certain temps de développement et de test, l’emploi du plugin Migrateur peut ne se justifier que dans le cadre d’un projet nécessitant plusieurs migrations successives.

Dans quel cas ne pas utiliser Migrateur ?

Pour une migration dont on sait qu’elle ne sera faite qu’une fois, ou si la surcharge du fichier migrateur/config.php n’est pas possible, ou encore si le scriptage des étapes supplémentaires est problématique, il est préférable d’effectuer cette migration à la main, ou d’utiliser d’autres plugins tels que le plugin « migration ».

Prérequis


-  le site source et le site cible doivent être sur le même serveur [2] Désormais le Migrateur fonctionne de serveur à serveur. Les commandes sont lancées sur le serveur source depuis le serveur cible après une identification par clés ssh
-  toutes les commandes étant exécutées par apache, ce dernier doit avoir le droit de lecture/écriture dans les dossiers IMG des deux sites ; apache et les users définis dans la config doivent pouvoir effectuer un dump de la base de prod, la poser dans tmp/dump du serveur cible et faire un source de cette base.
-  de même l’accès à la fonction exec() de php, ainsi qu’aux commandes mysqldump et rsync sur le serveur source sont nécessaires
-  il faut être en mesure de décrire les étapes sous forme de fonctions php, et de surcharger le fichier /migrateur/config.php (en écrivant un nouveau plugin par exemple)

Cas d’application

Le plugin Migrateur a été testé sur un serveur Apache avec PHP Version 5.3.18 et MySql 5.1.67 :
-  pour migrer un site de prod en SPIP2 vers un site de dev en SPIP 2
-  pour migrer un site de prod en SPIP 2 vers un site de dev en SPIP 3
-  pour migrer un site de prod en SPIP 3 vers un site de dev en SPIP 3

Comment utiliser Migrateur ?

Le plugin Migrateur va dupliquer les données d’un site source vers un site cible. Il doit être installé sur le site cible uniquement. Une fois le plugin installé, il faut surcharger le fichier config.php, soit en créant un plugin supplémentaire (par exemple « migrateur_monsite ») soit en ajoutant un fichier migrateur/config.php dans le dossier squelettes/. Commencer par indiquer les paramètres de connexion des sites source et cible, ainsi que les chemins vers leurs répertoires racine :

// Source
// -------
define('MIGRATEUR_SOURCE_DIR', '/sites/mon_domaine.fr/html/');

// SQL source
define('MIGRATEUR_SOURCE_SQL_USER', 'user_prod');
define('MIGRATEUR_SOURCE_SQL_PASS', '*******');
define('MIGRATEUR_SOURCE_SQL_BDD', 'db_prod');

// Destination
// -----------
define('MIGRATEUR_DESTINATION_DIR', '/sites/mon_domaine.fr/sd/dev/html/');

// SQL cible
define('MIGRATEUR_DESTINATION_SQL_USER', 'user_dev');
define('MIGRATEUR_DESTINATION_SQL_PASS', '*******');
define('MIGRATEUR_DESTINATION_SQL_BDD', 'db_dev');

// Nom du fichier d'export SQL
define('MIGRATEUR_NOM_EXPORT_SQL', 'export_source.sql');

Ensuite, compléter le tableau des étapes de migration :

// Etapes
$GLOBALS['MIGRATEUR_ETAPES'] = array(
 'mig_rsync_img'      => 'Synchroniser le répertoire IMG',
 'mig_exporter_bdd'   => 'Exporter la base source',
 'mig_transferer_bdd' => 'Importer dans la base destination',

A noter, le nom des fonctions du migrateur correspondent aux noms qu’on a donné aux étapes de migration, précédé de ’migrateur’. Par exemple l’étape ’mig_rsync_img’ correspond à la fonction function migrateur_mig_rsync_img() { du fichier de fonctions du migrateur.

Comment fonctionne Migrateur ?

Migrateur est accessible depuis le menu « maintenance » de l’espace privé. Si le fichier migrateur/config.php n’a pas encore été surchargé, un message d’erreur indique qu’il faut déclarer pour la source et la cible, le user, la base de données, le mot de passe et le nom du dossier racine du site.

Lors de la première exécution [3], le plugin Migrateur indique les paramètres qu’il va utiliser pour la migration. Vérifier que ces paramètres sont corrects et au besoin les changer dans la surcharge de migrateur/config.php.

Si les paramètres vous semblent corrects, vous pouvez exécuter l’étape 1 (par défaut la synchronisation du dossier IMG). Pour mémoire la commande serveur exécutée est la fonction rsync qui va effectuer une copie du dossier source vers la cible lors de la 1re exécution, puis ne va traiter ensuite que les différences (ajouts ou suppression de fichiers dans IMG).

Une fois l’étape 1 terminée, le résultat de l’exécution de l’étape est affichée dans un log en bas de page. Si tout s’est bien déroulé vous pouvez passer à l’étape suivante. En cas de souci, les logs vous seront utiles pour trouver la raison du dysfonctionnement et le corriger.

Vous pouvez ainsi passer d’une étape à l’autre suivant le même procédé (exécution, analyse des résultats, passage à l’étape suivante).

Lorsque le migrateur a passé toutes les étapes définies dans le fichier config.php, il revient automatiquement à l’étape N°1 qui est prête à être ré-éxécutée pour la prochaine migration.

Comment ajouter des étapes de migration supplémentaires ?

Les étapes à réaliser dépendent du type de migration à réaliser et des besoins de ceux qui en ont la charge. Voici comment ajouter votre propre étape.

Dans le fichier config.php, dans le tableau $GLOBALS['MIGRATEUR_ETAPES'] ajouter le nom de la fonction correspondant à l’étape que vous souhaitez créer, puis la description de cette fonction qui sera affiché sur la page du Migrateur.

$GLOBALS['MIGRATEUR_ETAPES'] = array(
 'mig_rsync_img'      => 'Synchroniser le répertoire IMG',
 'mig_exporter_bdd'   => 'Exporter la base source',
 'mig_transferer_bdd' => 'Importer vers la base destination',

 'xxx_fonction_1'     => "Description de la fonction 1",
 'xxx_fonction_2'     => "Description de la fonction 2",
 ...

Ensuite, créez la fonction correspondant dans votre fichier de fonctions. Voici quelques exemples de fonctions  :

Une fonction qui change le nom et l’url du cite cible

function migrateur_xxx_configurer_site() {
 migrateur_log("Modifier les métas");
 ecrire_meta('adresse_site', "http://dev.monnouveausite.net");
 ecrire_meta('nom_site', "Mon site SPIP *** VERSION DEV! ***");
}

Une fonction qui ajoute des plugins

function migrateur_xxx_activer_plugins() {
 migrateur_log("Activer les plugins");
 migrateur_activer_plugin_prefixes(array(
   'xxx_core',
   'xxx_skel',
   'xxx_theme',
 ));
}

Tableau récapitulatif des utilisations possibles du Migrateur

Type de migration Exemple type Plugin à utiliser Commentaires
SPIP 2 -> SPIP 2 le site de prod est sous SPIP 2, le site de développement aussi _plugins_/migrateur/branches/v1
SPIP 2 -> SPIP 3 le site de prod est sous SPIP 2, mais le site de développement est sous SPIP 3 _plugins_/migrateur/trunk Le migrateur est à utiliser sur le site de destination, on choisit la version du plugin en fonction de la version de SPIP installée sur le serveur de destination
SPIP 3 -> SPIP 3 le site de prod est sous SPIP 3, le site de développement aussi _plugins_/migrateur/trunk

Notes

[1écart de version maximum : SPIP 2.1 - SPIP 3.0

[2une version de Migrateur fonctionnant à base de clés ssh est en cours d’étude

[3ou lorsque les logs ont été vidés

Discussion

2 discussions

  • 5

    Bjr

    Est ce que ça peut permettre la migration de SQLite en MySQL ?
    Cordialement

    • Bonjour,
      par défaut, non. Il faudrait sans doute scripter cette action dans une fonction

      function migrateur_changer_bdd() {

      par exemple. Je ne sais pas s’il existe déjà une commande pour passer d’un type de base de données à l’autre, et si c’est le cas la fonction de migration est très facile à écrire.

    • Merci de la réponse,

      Ce n’est pas très facile pour un néophyte ;-)
      J’ai bien essayé la manip en lignes de commande porposée ici, mais ça plante à la dernière étape ...
      Donc, si vous aviez l’extraordinaire pouvoir de générer cette fonction, je crois, à en lire les forums, que cela rendrait service à beaucoup de monde ^^
      Cordialement

    • Si l’opération de migration de la bdd de SQLite en MySql n’est à faire qu’une seule fois, je ne suis pas certain que l’emploi du migrateur soit un bon choix ; il vaudrait mieux peaufiner une bonne procédure manuelle fonctionnelle, en complétant ce qui a été proposé sur le carnet.
      En revanche si l’opération est à faire plusieurs fois, ça vaudrait le coup de la scripter, y compris l’opération de passage de SQLite vers MySql. Malheureusement je n’ai pas la possibilité d’écrire ce script pour l’instant.

    • Théoriquement, cette opération est aussi possible par le plugin Migration de Nursit (si les deux serveurs sont sur l’internet).. /non testé/

    • Ce n’est pas théoriquement, mais c’est assurément possible avec le plugin Migration ;-)

      La différence essentielle entre les deux plugins, c’est que le Migrateur permet d’ajouter des opérations durant le processus de migration, ce qui est particulièrement utile pour moduler le site de destination (le site migré) selon ses besoins. De plus le Migrateur est capable de ne migrer parmi les données du dossier IMG, que celles qui ne sont pas déjà sur le site de destination (processus similaire à celui de rsync).

      Migration va effectuer la copie d’un site vers un autre, alors que le Migrateur va être en mesure de transformer un site (de prod, par exemple) en un autre site (de dev, par exemple). Et désormais le Migrateur fonctionne via http (cf la démo de Matthieu durant la dernière SPIP Party à Toulouse) avec un chiffrement des données, entre deux plate-formes d’hébergement distinctes.

      Les deux plugins peuvent être utilisés selon les besoins, que l’on peut résumer ainsi :
      -  copie conforme en one-shot : plugin Migration
      -  copies répétitives [1] avec transformation : plugin Migrateur

    Répondre à ce message

  • Super plugin.La migration d’un gros site étant assez complexe, ce plugin vient découper la procédure en plusieurs petites étapes qui permettent de ne pas planter le site de production en cas de difficulté.Je trouve que c’est bien documenté et facile à prendre notamment grâce aux exemples fournis.
    Beau boulot Cyril !!!

    Répondre à ce message

Ajouter un commentaire

Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :

  • Désactiver tous les plugins que vous ne voulez pas tester afin de vous assurer que le bug vient bien du plugin X. Cela vous évitera d’écrire sur le forum d’une contribution qui n’est finalement pas en cause.
  • Cherchez et notez les numéros de version de tout ce qui est en place au moment du test :
    • version de SPIP, en bas de la partie privée
    • version du plugin testé et des éventuels plugins nécessités
    • version de PHP (exec=info en partie privée)
    • version de MySQL / SQLite
  • Si votre problème concerne la partie publique de votre site, donnez une URL où le bug est visible, pour que les gens puissent voir par eux-mêmes.
  • En cas de page blanche, merci d’activer l’affichage des erreurs, et d’indiquer ensuite l’erreur qui apparaît.

Merci d’avance pour les personnes qui vous aideront !

Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.

Qui êtes-vous ?
[Se connecter]

Pour afficher votre trombine avec votre message, enregistrez-la d’abord sur gravatar.com (gratuit et indolore) et n’oubliez pas d’indiquer votre adresse e-mail ici.

Ajoutez votre commentaire ici

Ce champ accepte les raccourcis SPIP {{gras}} {italique} -*liste [texte->url] <quote> <code> et le code HTML <q> <del> <ins>. Pour créer des paragraphes, laissez simplement des lignes vides.

Ajouter un document

Suivre les commentaires : RSS 2.0 | Atom