Migration Drupal 9 vers Drupal 10

Le contexte

Ce site fonctionne avec un CMS Drupal, Drupal 7 lors de sa création (en 2012!). Depuis, il a été migré en Drupal 8, cette migration ayant été la plus complexe, puisque le produit passait d'un code 100% spécifique à une architecture basée sur Symfony.

La migration Drupal8 vers Drupal9 s'est passée beaucoup plus facilement, en modifiant essentiellement les paramètres du composer.

Drupal 10 a été mise à disposition du grand public en décembre 2022. 

Afin de pouvoir disposer des dernières mises à jour et fonctionnalités, je vais migrer le site en Drupal 10.

Méthodologie

Afin d'éviter une interruption de service trop longue, et pour tester la mise à jour, j'ai d'abord remonté une VM à l'identique de ma production : 

• Debian11, 
• MariaDB (10.5.21), 
• PHP 8.1 et ses modules nécessaires, 
• nginx.

Le site (base de données et fichiers) a été exporté de la production, et importé sur la nouvelle VM. La configuration du Drupal est adaptée à mon URL de test, et je vérifie que tout fonctionne correctement dans la version 9, avant de faire les manipulations pour la migration.

En production, afin de pouvoir faire un retour en arrière rapide, on va dupliquer la base de données et l'arborescence. Dans un premier temps, on aura donc 2 "sites" identiques, dont l'un va passer en version 10. En cas de souci, il suffira de modifier le paramétrage du frontal nginx pour passer de la version 10 à la version 9.

Prérequis système

Drupal 10 nécessite :

• nginx 1.1 ou plus
• mariadb 10.3.7 ou plus (on est e 10.5.21)
• 1 Go de RAM
• PHP avec 256Mo
• php 8.1
• extensions php : pdo, xml, gd, openssl, json, curl

L'installation a été faite via le dépôt packages.sury.org, puisque php8 n'est pas disponible en natif sur Debian 11. Dans mon cas, j'avais déjà fait l'installation pour Drupal 9.

# Recuperation du repo php-sury

wget https://packages.sury.org/php/apt.gpg -O /usr/share/keyrings/deb.sury.org-php.gpg
echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ bullseye main" >  /etc/apt/sources.list.d/php.list

# installation php8.1

apt install php8.1-cli php8.1-fpm php8.1-pdo php8.1-mysql 
apt install php8.1-xml php8.1-curl php8.1-gd  php8.1-mbstring php-bcmath

Il faut également s'assurer que composer est disponible sur le serveur, dans une version > 2.3.

Une fois les prérequis installés, on vérifie la configuration php8.1 et nginx, avec un vhost correct.

Vérifications préalables

Documentation : Upgrading from Drupal 9 to 10

Modules non compatibles

Dans la page d'extensions, on peut voir les modules dépreciés, et qu'on doit supprimer. Dans mon cas, :

• CKEditor (que j'utilise)
• Color (pas utilisé)
• Aggregator (pas utilisé)
• Quick Edit (utilisé)
• RDF (utilisé)
• HAL (pas utilisé)

Dans mon cas, je vais déinstaller les modules CKEditor, Color, Aggregator et RDF, et installer / activer le module CKEditor5.

Attention : afin d'éviter de perdre la configuration de l'éditeur de texte, il faut d'abord :

• activer le module CKEditor 5
• modifier chaque format de texte pour utiliser CKEditor5 en lieu et place de CKEditor
• vérifier que la mise à jour des articles est OK
• désinstaller le module CKEditor

Il faut ensuite repasser sur chaque format de texte pour préciser l'éditeur de texte à utiliser.

Note ceci peut être fait sur la version Drupal 9.

Thèmes non compatibles

Différents thèmes sont dépréciés.

Il faudra supprimer :

• stable
• classy
• bartik
• seven

Note : comme mon thème spécifique utilise Classy comme base, il ne pourra pas être supprimé avant de migrer.

Afin d'éviter des problèmes à la migration, il vaut mieux temporairement utiliser un thème standard.

Lancer la mise à jour

Afin de limiter l'indisponibilité et pour faire un retour en arrière rapide, on va :

• faire une copie de l'arborescence drupal9 en drupal10
• extraire les données de la base, et les réimporter dans une autre database

Voir la documentation Drupal

On prépare les dossiers

chmod 777 web/sites/default
chmod 666 web/sites/default/*settings.php
chmod 666 web/sites/default/*services.yml

Lancer la mise à jour avec Composer. Pour l'instant, on met uniquement à jour le fichier composer.json (avec l'option --no-update).

composer require 'drupal/core-recommended:^10' 'drupal/core-composer-scaffold:^10' 'drupal/core-project-message:^10' --update-with-dependencies --no-update
composer require 'drupal/core:^10' --update-with-dependencies --no-update
composer require 'drupal/core-dev:^10' --dev --update-with-dependencies --no-update
composer require 'drush/drush:^12' --no-update

Il faut également vérifier les versions des modules. Dans mon cas, ce sera :

• colorbox : 2.0
• honeypot : 2.1
• pathauto : 1.12
• tagclouds : 2.0
• token : 1.12
• xmlsitemap : 1.15

Ceci peut être fait via la commande

composer require 'drupal/xmlsitemap:^1.5' 'drupal/colorbox:^2.0' 'drupal/honeypot:^2.1' --no-update

Une fois ceci effectué, on peut lancer la mise à jour elle-même

composer update

A ce niveau, il faut modifier le thème custom pour ne plus le faire dépendre de classy.

vendor/drush/drush/drush theme:install starterkit_theme

Il faut donc modifier le fichier info.yml du thème. Pour ma part, ceci devient :

description: Un theme Drupal BootStrap / StarterKit pour le site vincentliefooghe.net
core: 10.x
core_version_requirement: ^8 || ^9 || ^10
base theme: starterkit_theme
package: custom
version: 10.0.1

J'ai également dû installer le thème classy, avant de pouvoir faire la mise à jour de la BDD correctement

composer require 'drupal/classy:^1.0'

Puis on fait les mises à jour de la base de données

drush updatedb

Et on reconstruit le cache

vendor/drush/drush/drush cache:rebuild

Soucis rencontrés

Mon thème spécifique s'appuyait sur le thème Classy, qui n'existe plus avec Drupal 10.

vendor/drush/drush/drush theme:install starterkit_theme

Il faut également modifier le fichier .info.yml du thème pour hériter de starterkit

La configuration Nginx doit également être modifiée pour Drupal 10, sur les aspects files, sinon les CSS ne sont pas pris en compte correctement  :

Modifier:

location ~* /files/styles/ {
  access_log off;
  expires 1d;
  try_files $uri @rewrite;
}

En :

location ~*/files/(css|js|styles)/ {
  access_log off;
  expires 1d;
  try_files $uri @rewrite;
}

On peut ensuite positionner les bons droits sur les répertoires / fichiers

chmod 755 web/sites/default
chmod 444 web/sites/default/settings.php