Migrer un site auto-hébergé de la v2 ou de la v3 à la v5

S'applique à : auto-hébergé, Dokos v2 ou v3 → v5. Pour un site v4, voir Migrer de la v4 à la v5.

Il n'est pas possible de restaurer directement une base v2 ou v3 sur une v5. Les patchs de migration supposent que la base est dans l'état de la version précédente. Sautez une version et de nombreux patchs échouent : un champ à renommer n'existe pas encore, une table attendue manque. Corriger ces erreurs une par une est long, et la base peut garder des incohérences.

Passez donc une version majeure à la fois.

Les paliers

« Ubuntu LTS à cette date » est la dernière version LTS d'Ubuntu sortie avant la version de Dokos. Python et Node.js sont les versions que le code de Dodock exige sur la branche : setup.py ou pyproject.toml pour Python, package.json pour Node.js. « Testé » indique la version de l'intégration continue de Dokos quand le code ne fixe pas de minimum.

Le Python fourni par Ubuntu est 3.8 sur 20.04, 3.10 sur 22.04 et 3.12 sur 24.04. Sur Ubuntu 22.04, les étapes 1 et 2 utilisent donc le Python du système. Pour l'étape 3, installez Python 3.14 à côté de celui du système, ou utilisez Docker. Installez toujours Node.js depuis NodeSource ou nvm.

Nouvelles applications à ajouter à chaque palier :

• v3 : Payments, HRMS et, si vous l'utilisez, WooCommerce sortent de Dokos.
• v4 : Webshop sort de Dokos.
• v5 : Blog, Energy Points, Newsletter et Backup Integrations sortent de Dodock. eTransactions remplace OCR.

Préparer la machine

Les anciennes versions de Python et de Node.js ne s'installent pas toujours sur un système récent. Deux approches :

• Une machine de migration jetable. Montez une machine virtuelle avec l'Ubuntu LTS de l'étape en cours (voir le tableau). Mettez le système à niveau entre deux paliers, ou changez de machine à chaque palier en déplaçant la sauvegarde.
• Le serveur existant. Mettez à jour le système d'exploitation par étapes, en parallèle des paliers Dokos. Après chaque mise à jour du système, vérifiez que bench démarre avant de continuer.

Dans les deux cas, gardez le serveur de production d'origine intact jusqu'à la fin.

Procédure pour chaque palier

1. Sauvegardez le site : bench --site dokompany.fr backup --with-files. Copiez la sauvegarde et site_config.json hors de la machine.
2. Installez les versions de Python et de Node.js du palier, à côté de celles du système (voir ci-dessous).
3. Migrez l'environnement du bench, ou créez un nouveau bench avec la bonne version de Python et déplacez-y le dossier du site.
4. Ajoutez les nouvelles applications du palier.
5. Changez de branche avec bench switch-to-branch.
6. Installez les nouvelles applications sur le site, lancez bench update --reset, puis vérifiez le site.
7. Passez au palier suivant seulement si le site fonctionne.

Arrivé en v4, vous pouvez finir par le chemin Docker : sauvegardez le site v4 et restaurez-le sur une installation Docker v5.

Installer Python et Node.js à côté du système

Ne remplacez jamais le Python du système. Des outils comme apt en dépendent. Sous Ubuntu, utilisez le dépôt deadsnakes pour Python et NodeSource (ou nvm) pour Node.js. Exemple pour le palier v3 → v4 :

wget -qO- https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.10 python3.10-dev python3.10-venv
curl -sS https://bootstrap.pypa.io/get-pip.py | python3.10
pip install dokos-cli --upgrade

Remplacez 18 par 16 pour le palier v2 → v3. Vérifiez ensuite avec node --version et python3.10 -V.

Chaque bench est un environnement virtuel Python séparé. Seul docli (paquet dokos-cli) utilise le Python par défaut du système.

Palier v2 → v3

bench migrate-env python3.10
bench get-app https://gitlab.com/dokos/payments --branch v3.x.x
bench get-app https://gitlab.com/dokos/hrms --branch v3.x.x
bench get-app https://gitlab.com/dokos/woocommerce --branch v3.x.x   # seulement si vous utilisez WooCommerce
bench switch-to-branch v3.x.x frappe erpnext --upgrade
bench --site dokompany.fr install-app payments
bench --site dokompany.fr install-app hrms
bench update --reset

Payments est obligatoire à partir de la v3. Au début de la migration, des messages d'erreur SQL sur des champs inconnus peuvent apparaître. Ils disparaissent quand les patchs qui créent ces champs ont tourné.

Palier v3 → v4

Si le bench est déjà en Python 3.10, sautez la commande migrate-env.

bench migrate-env python3.10
bench get-app https://gitlab.com/dokos/webshop --branch v4   # seulement si vous utilisez l'e-commerce
bench switch-to-branch v4 frappe erpnext hrms payments --upgrade
bench --site dokompany.fr install-app webshop
bench update --reset

À partir de la v4, les scripts serveur sont désactivés par défaut. Pour les activer, lancez bench set-config -g server_script_enabled 1. Ce réglage existe seulement au niveau du bench.

Exemple

Un site Dokompany tourne en v2 sur Debian 10. L'administrateur monte une machine de migration, restaure la sauvegarde v2, puis passe en v3, en v4 et en v5. Il met le système à jour entre deux paliers. Il garde une sauvegarde à chaque palier. À la fin, il restaure la sauvegarde v4 sur une nouvelle machine Docker v5.

Vérifier

À chaque palier :

• bench --site dokompany.fr migrate se termine sans erreur.
• Vous vous connectez et ouvrez une facture, un article et un client.
• Aide > À propos affiche la version attendue.

Problèmes fréquents

Pour toute question, ouvrez un sujet sur le forum de la communauté avec la version d'origine et le message complet.