Migrer un site WordPress en local dans une stack Docker – Tutoriel Complet

docker kubernetes

Dans ce post nous allons voir comment migrer une installation complète d’un site WordPress depuis votre hébergeur vers votre machine en local en utilisant Docker. Pour cela,  je vous propose d’effectuer les opérations suivantes :

  • récupération des fichiers et des données depuis l’hébergeur
  • montage d’une Stack dans Docker pour faire fonctionner un serveur PHP avec WordPress, un serveur de bases de données MySQL et un applicatif de gestion de la base de données Adminer, avec disques virtuels partagés dans Windows (WSL2)
  • intégration des fichiers dans le WordPress local
  • intégration des données dans la base MySQL locale
  • paramétrage de l’installation locale
  • fixs d’éventuelles erreurs et conseils additionnels

Posséder une version de son site en local, avec une installation qui possède une faible adhérence avec le système d’exploitation de votre machine à de nombreux intérêts :

  • constituer une sandbox qui permet d’effectuer hors production des modifications sur le site web sans crainte de perturbation ou de destruction de celui-ci. Les modifications locales pourront être reportées sur le site de production une fois seulement celles-ci validées (installation de modules, modification de thèmes et de styles, customisation, rédaction de contenus, …)
  • bénéficier d’une meilleure bande passante (pas de dépendance avec internet) et ne pas solliciter inutilement votre site en production (problèmes de charges, dégradation de l’expérience de vos utilisateurs, … )
  • analyser en profondeur votre installation de WordPress (modules, base de données) et faire des modifications (suppressions directes en base, modification des modules) d’une manière bien plus pratique et rapide que via FTP, et dans tous les cas réversibles

La procédure de migration est décrite ici en 10 points

1. Récupération des fichiers et des données du site WordPress

1.1. Transfert des fichiers

A partir de votre client FTP préféré (Filezilla dans mon cas), connectez vous sur le serveur FTP de votre hébergeur lié à votre site web, à la racine du système de fichiers de WordPress:

fichiers dans filezilla
fichiers dans filezilla

il faut copier les fichiers de la racine / , et les répertoires wp-admin, wp-content, wp-includes. Ignorez les répertoires backup et cache (souvent dans wp-content) vers le répertoire local de votre choix. Pour la suite, on prend comme répertoire c:/docker-volumes/remote-files/ comme répertoire de copie des fichiers en local.

1.2. Transfert des données

A partir de l’outil de gestion de bases de données mis à disposition par votre hébergeur (vous pouvez sauter cette étape si vous possédez un backup SQL de la base de données WordPress, sous la forme d’un script de création de la base, et le récupérer localement), il faut effectuer un export SQL de la base sous la forme d’un script de création. Par exemple, avec PhpMyAdmin, avec focus sur quelques options importantes :

mysql 1/3
options mysql 1/3
options mysql 1/3
options mysql 2/3
mysql 2/3
options mysql 3/3

Focus particulier sur l’option « Désactiver la vérification des clefs étrangères » et « exporter les méta données », important pour obtenir une base iso et abaisser le coût de l’import/export. Pour la suite on considère que le script de création de la base est stocké dans c:/docker-volumes/localhost.sql

2. Préparation de la stack Docker

2.1. Installation de Docker Desktop

pré-requis (sous windows):

Deux options sont possibles, selon le type de virtualisation impliqué par le stockage virtuel. Il est préférable d’activer les deux possibilités:

backend WSL 2:

  • Windows 11 64-bit: Home or Pro version 21H2 ou plus, ou Enterprise ou Education version 21H2 ou plus
  • Windows 10 64-bit: Home or Pro 2004 (build 19041) ou plus, ou Enterprise or Education 1909 (build 18363) ou plus
  • Activation de la fonctionnalité WSL 2 dans Windows
  • processeur 64bits avec SLAT (Second Level Address Translation)
  • 4Gb RAM
  • support hardware de la virtualisation activée dans le BIOS

L’installeur de WSL 2 est disponible ici: Installer WSL 2 | Microsoft Docs

backend Hyper-V et containers windows:

  • Windows 11 64-bit: Home or Pro version 21H2 ou plus, ou Enterprise ou Education version 21H2 ou plus
  • Windows 10 64-bit: Home or Pro 2004 (build 19041) ou plus, ou Enterprise or Education 1909 (build 18363) ou plus
  • Activation de la fonctionnalité Hyper-V et containers windows activés dans windows
  • 4Gb RAM
  • support hardware de la virtualisation activée dans le BIOS
  • backend Hyper-V et containers windows

L’installeur de Docker Desktop pour windows est disponible ici: https://desktop.docker.com/win/main/amd64/Docker Desktop Installer.exe

Cochez toutes les options dans la première étape, attendez et redémarrez votre ordinateur. Une fois l’ordinateur démarré, lancez Docker Desktop à partir de l’icône sur le bureau:

docker shortcut
docker shortcut

La fenêtre de Docker Desktop doit s’ouvrir, mais ne faites rien avec pour l’instant (fermez les éventuels pop-ups et tutoriaux). L’icône de la baleine doit s’afficher dans la zone de notification de la barre des tâches.

2.2. Configuration et lancement de la stack docker

2.2.1. Configuration de la stack

Ouvrez le fichier c:/docker-volumes/remote-files/wp-config.php dans un éditeur de texte (recommandé: VSCode). Notez les paramètres de connexion à la base de données comme dans l’exemple ci-après:

wp-config.php
wp-config.php

DB_NAME: nom de la base de données
DB_USER: utilisateur de la base de données
DB_PASSWORD: password de l’utilisateur de la base de données
A partir de votre contrat d’hébergement, vous devez connaître votre nom de domaine, de la forme:
HOST: http://franckgaspoz.fr

La stack est décrite par un fichier
YAML qui définit 3 machines linux: l’une contenant un serveur PHP qui fait tourner WordPress, à l’adresse http://franckgaspoz.fr, une autre qui fait tourner le serveur MySQL sans exposition sur le réseau externe à la stack et une autre contenant un serveur PHP qui fait tourner Adminer à l’adresse http://localhost:81

Copiez le fichier wordpress-mysql-adminer-stack.yaml depuis l’archive:

wordpress-mysql-adminer-docker-stack.zip

dans le répertoire de travail que nous avons défini pour cette opération: c:/docker-volumes/. Ouvrez le fichier dans un éditeur de texte, et substituez les paramètres WORD_PRESS_DB_HOST, WORDPRESS_DB_USER, WORDPRESS_DB_NAME et MYSQL_DATABASE, MYSQL_USER, MYSQL_PASSSWORD par les valeurs DB_NAME, DB_USER, DB_PASSWORD trouvées précédemment:

wordpress-mysql-adminer-stack.yaml
wordpress-mysql-adminer-stack.yaml

2.2.2. Lancement de la stack

La stack est prête pour être lancée. Ouvrez une fenêtre console PowerShell ou dos (ou bash sous linux) et entrez la commande:

cd c:/docker-volumes/
docker-compose -p wordpress-install -f wordpress-mysql-admliner-stack.yml up

Ceci indique à docker de lancer une stack (machines et réseaux virtuels), nommée wordpress_install à partir du fichier de définition de stack indiqué. Dans ce mode on peut suivre les logs directement car la machine est lancée sans démon (mode démon activé avec -d). Au lancement, docker fabrique va chercher les images des machines virtuelles indiquées dans le YAML (WordPress plus récente, MySQL version 5.7 et Adminer plus récente). Après téléchargement il fabrique les containers et démarre les instances:

run stack
run stack

Le lancement en non deamon permet de visualiser les logs des applicatifs directement dans la console. Chaque entrée de log est préfixée par le nom du container qui produit le log.
Le lancement va provoquer l’initialisation des disques virtuels et leur montage dans des dossiers, ce qui va produire le warning suivant:

docker warning
docker warning

Car nous avons fait le choix de partager les fichiers dans l’hôte (Windows) et non pas de les conserver dans le container docker qui hébergent nos containers. Les disques virtuels sont mountés , d’après notre configuration, aux emplacements suivants, et on peut maintenant y accéder:

mounts
mounts

Dans une deuxième fenêtre de console (SHIFT+ALT+D dans windows terminal), on peut entrer la commande pour visualiser les containers actifs dans docker:

docker ps

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
deff6b1bbeab wordpress "docker-entrypoint.s…" 31 minutes ago Up 31 minutes 0.0.0.0:8080->80/tcp wordpress-install_wordpress_1
4127be165487 mysql:5.7 "docker-entrypoint.s…" 31 minutes ago Up 31 minutes 3306/tcp, 33060/tcp wordpress-install_db_1
83d8b9c153d3 adminer "entrypoint.sh docke…" 31 minutes ago Up 31 minutes 0.0.0.0:81->8080/tcp wordpress-install_adminer_1

A ce stade, si on se connecte sur l’adresse du site WordPress en local, on obtiendra le formulaire d’installation, car la base de données MySQL n’est pas encore initialisée. Mais on a pas besoin de paramétrer l’installation via l’auto-setup web:

install form
install form

Par contre l’initialisation des containers à également entrainé l’initialisation des disques virtuels et leur mappage dans les dossiers windows indiqués dans la configuration.
Pour arrêter la stack, on peut utiliser la combinaison de touches CTRL+C dans la console ou on a lancé la commande up (si pas option -d), ou la commande:

cd c:/docker-volumes/
docker-compose -p wordpress-install -f wordpress-mysql-admliner-stack.yml down

dans une autre console si pas option -d (mode deamon). Les disques virtuels sont conservés dans Windows et toujours accessibles (ils sont persistants). La prochaine commande up reconnectera les disques et le site sera tel que dans dans l’état avant l’arrêt de la stack.

2.2.3. Importation des fichiers de l’installation WordPress

La première étape pour cloner le site de production dans le container consiste à recopier les fichiers depuis la copie locale. Ceci se fait simplement en copiant le contenu du répertoire c:/docker-volumes/remote-files/ dans le répertoire c:/docker-volumes/wordpress , en écrasant tous les fichiers de destination.

2.2.3. Importation des données

Pour importer les données, il faut se connecter avec un navigateur à l’outil web Adminer à l’adresse http://localhost:81 , puis se logger en renseignant les informations déjà fournies dans le YAML de configuration de la stack:

login adminer
login adminer

Ensuite via l’interface, renseigner indiquer le script de création SQL stocké dans c:/docker-volumes/localhost.sql :

db import
db import

A la fin de l’import, on peut voir la liste des tables s’afficher ainsi qu’un message indiquant le succès de l’opération :

data imported
data imported

3. Paramétrage de l’installation locale

3.1. Changement de host

3.1.1. Références dans la base de données

Il faut maintenant apporter des modifications aux settings de WordPress afin de le migrer depuis le host de production (dans l’exemple http://franckgaspoz.fr) vers l’host local http://franckgaspoz.fr. On va commencer par modifier toutes les références que l’on trouve dans la table wp_options de la base de données de WordPress, via Adminer. Les principales références au host sont les options (option_name) siteurl et sithome, ici changées :

wp options
wp_options

Il faut également rechercher la valeur du host de production dans toutes les valeurs des options pour faire un changement de host complet. En effet, n’importe quel module WordPress est susceptible d’enregistrer le host dans ses données de travail. Pour cela une requête SQL peut être construite avec Adminer:

SELECT *
FROM `wp_options`
WHERE `option_name`LIKE '%franckgaspoz.fr%'

A titre d’exemple, le résultat m’a indiqué les données d’un module de cache CDN ainsi que des données du module de menus (qui est intégré dans WordPress dans ma distribution par défaut). Il a convenu de corriger les valeurs:

wp-options
wp_options

Et de supprimer ce qui apparraissait être des données temporaires du module de menu, mais entraînait des liens vers le site de production dans les menus de l’installation locale au lieu de liens qui pointaient vers localhost:

DELETE
FROM `wp_options`
WHERE `option_name` LIKE '%transient_menu-cache%'

Il peut y avoir d’autres références dans wp_options qu’il faudra tenter de remplacer en affinant les requêtes SQL employées. Il y a également un référence à remplacer dans la table wp_postmeta :

wp_postmeta
wp_postmeta

3.1.1. Références dans les fichiers de l’installation de WordPress

Ouvrez le fichier c:/docker-volumes/wordpress/.htaccess dans  dans VSCode, et commentez les redirections d’URLs (si vous les avez) suivantes:

.htaccess

De mon côté j’ai également un module de cache front qui fonctionne en utilisant la réécriture d’URLs, j’ai préféré le désactiver dans le .htaccess pendant la phase de test en commentant les règles correspondantes:

.htaccess cache rewrite rules

3.2. Configuration de WordPress

Ouvrez le fichier c:/docker-volumes/wordpress/wp-config et modifiez le en ajoutant le premier bloc indiqué ci-après (cadre rouge) et en modifiant les lignes suivantes par le deuxième bloc. Ceci permet de récupérer la configuration de la stack Docker et de l’injecter directement dans les settings de l’application:

wp-config docker
wp-config docker

Au passage on va ajouter quelques lignes de PHP dans ce fichier pour empêcher PHP d’afficher des warnings et des erreurs dans la page WEB. Ce réglage serait également le bienvenu en production:

php trace conf
php trace conf

La stack contient la dernière version de WordPress avec une version très récente de PHP (à priori last stable release), ce qui ne correspond pas exactement avec la version du code PHP que nous avons intégré dans la stack Docker (fichiers de production). Nous allons potentiellement faire face à des erreurs (mineures) de compatibilité du langage. Ces erreurs sont faciles à détecter car elles donnent lieu à une erreur de header HTTP (envoi multiple), avec une trace qui indique les fichiers concernés. Ces cas de figure vont varier en fonction des versions du langage et des modules installés et activés dans WordPress:

header information
header information

Dans un tel cas, l’erreur est liée au premier fichier indiqué dans la trace qui a surement produit un message d’erreur impliquant l’envoi du header HTTP. Il faut éditer le fichier en question et examiner le code à la ligne indiquée. En général, dans notre cas il devrait s’agir d’un problème de compatibilité mineure (le site marche en production non?), et commenter la ligne en question devrait résoudre le problème. Comme dans ce cas (pourtant le module fonctionne parfaitement..) :

category-to-pages-wud.php
category-to-pages-wud.php

4. Utilisation du site en local

4.1. Accès

Comme indique précédemment, le site est accessible (lorsque la stack est up) à l’adresse: http://franckgaspoz.fr . On vérifie via un navigateur WEB que tout est bien en ordre de marche:

localhost:8080
localhost:8080

Contrôler les logs des machines de la stack permet de vérifier que tout fonctionne correctement:

stack logs
stack logs

L’accès à l’administration du site se fait par l’url habituelle http://franckgaspoz.fr/admin , le login/password est inchangé par rapport à la production:

wordpress admin log in
wordpress admin log in

4.2. Installation d’extensions

WordPress à besoin d’accéder à un serveur FTP connecté au site pour réaliser la récupération d’extensions (téléchargement et sauvegarde parmi les fichiers du site).  N’ayant pas abordé cette installation, on peut utiliser un contournement simple pour effectuer une installation: Utiliser le site en production pour effectuer le téléchargement du plugin à la place.

La manipulation complète est la suivante:

  • depuis le site de production, interface d’administration WordPress, page extensions, ajouter, cliquer sur le bouton « installer » l’extension choisie. Je prend comme exemple l’installation d’une nouvelle extension: Equation Editor. Après sélection de l’extension, cliquez sur le bouton installer
  • une fois que l’extension est installée, on ne fait rien d’autre.  A ce stade l’extension a seulement été téléchargée et n’est pas activée. Le site de production n’a donc pas été impacté
  • à l’aide d’un client FTP, récupérer les fichiers de l’extension qui ont été copiés dans un répertoire dans /wp-content/plugins/ . Un nouveau dossier à du apparaître, dans notre cas il se nomme equation-editor. Le dossier doit être transféré dans le répertoire du site en local correspondant ( C:/docker-volumes/wordpress/wp-content/plugins/ ).
  • rendez vous sur le site en local, sur la page d’administration, extensions. L’extension Equation Editor apparaît dans la liste, cliquez sur le bouton activer

4.3. Transférer un post rédigé en local vers le site de production

4.3.1. Exporter le post

Cela est possible en utilisant la fonctionnalité intégrée dans le bundle par défaut WordPress. Dans le menu outil, exporter, sélection de l’item article, sélection par la date la plus récente et cliquer sur le bouton télécharger le fichier d'export.

remarque: penser à exporter un post dans l’état « brouillon », car il conservera son statut lors de l’import. Si il est importé à l’état publié il sera publié automatiquement au moment de l’import et les éventuelles extensions qui s’activent lors de la publication ne seront pas exécutées (par exemple, publication sur les réseaux sociaux)

Ouvrir maintenant le fichier d’export XML dans VSCode. Il faut changer le host http://localhost:8080 par le host de production (dans l’exemple http://franckgaspoz.fr) en utilisant la fonction rechercher/remplacer (CTRL+H) et sauver le fichier.

4.3.2. Exporter les media du post

Effectuer la même manipulation que précédemment, en sélectionnant cette fois la catégorie media. Jouer avec les filtres pour sélectionner uniquement les médias du post. Comme pour le post, il faut modifier le host dans VSCode et sauver le fichier.  Cet import/export va permettre de  créer dans le WordPress de production les documents media correspondants au post.

Les fichiers images doivent être transférés manuellement (avant l’import des documents media). Pour cela, utiliser Filezilla et copier les fichiers correspondants a l’export des media depuis le répertoire du site local C:/docker-volumes/wordpress/wp-content/uploads/2021/11 (corriger les dossiers de l’année et du mois en fonction de votre cas) vers le répertoire du site de production /wp-content/uploads/2011/11 (corriger les dossiers de l’année et du mois en fonction votre cas) .

4.3.3. Importer le post

Depuis le site de production, en utilisant également la fonctionnalité intégrée d’import, dans le menu outil, cliquer sur catégorie WordPress, puis sélectionner le module WordPress importer (si son installation est proposée c’est que l’extension ne l’est pas encore, il faut alors cliquer sur installer). Puis cliquer sur lancer l'importer.  Sélectionner le fichier exporté précédemment, puis cliquer sur Lancer le téléchargement. Parmi les options proposées, choisir un auteur existant. L’auteur du site local ne sera pas reconnu comme existant sur le site de production. L’option téléverser et importer les fichiers joints n’est pas utile pour cet import, inutile de la cocher.

4.3.4. Importer les media

Depuis le site de production, en utilisant également la fonctionnalité intégrée d’import, dans le menu outil, cliquer sur catégorie WordPress, puis sélectionner le module WordPress importer, en cliquant sur le boutonlancer l'importer.  Sélectionner le fichier exporté précédemment, puis cliquer sur Lancer le téléchargement. Parmi les options proposées, choisir un auteur existant. L’auteur du site local ne sera pas reconnu comme existant sur le site de production. Cette fois il faut bien cocher l’option téléverser et importer les fichiers joints pour que les fichiers media soit liés aux documents médias.

4.3.5. Vérification

Sur la page d’administration des media, les nouveaux media importés doivent apparaître. Sur la page d’administration des articles, on doit voir l’article qui a été transféré (d’après les préconisations il doit être à l’état « brouillon »). Cliquer sur l’article pour l’éditer et vérifier son contenu.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Merci de votre lecture. Utilisez le formulaire au bas de la page pour faire part de vos remarques et commentaires

Laisser un commentaire