Migrer un site auto-hébergé de la v4 à la v5

S'applique à : auto-hébergé, Dokos v4 → v5. Sur Dokos Cloud, voir Mettre à jour un site Dokos Cloud.

La v5 change les prérequis du serveur. Le bench existant ne peut pas simplement être mis à jour.

Ubuntu 24.04 ne fournit pas Python 3.14. Installez-le à côté du Python du système (voir plus bas), ou utilisez Docker. Pour les étapes plus anciennes, voir Migrer de la v2 ou de la v3 à la v5.

Deux chemins existent. L'équipe Dokos recommande le premier.

Chemin recommandé : nouvelle machine Docker et restauration

Vous installez la v5 avec Docker sur une nouvelle machine, puis vous y restaurez la sauvegarde du site v4. L'ancien serveur reste intact : c'est votre retour arrière.

Prérequis

• Une nouvelle machine Linux avec Docker. Voir Installation Docker.
• La liste des applications installées sur le site v4 : bench --site dokompany.fr list-apps.
• L'image Docker par défaut installe Payments, Dokos, HRMS et Webshop. Si votre site utilise d'autres applications, construisez une image personnalisée qui les contient, en version v5.

Sauvegarder le site v4

cd ~/dokos-bench
bench --site dokompany.fr backup --with-files
cat sites/dokompany.fr/site_config.json   # notez la valeur encryption_key

Copiez les quatre fichiers de sites/dokompany.fr/private/backups/ vers la nouvelle machine.

Restaurer sur la v5

docker compose up -d
docker compose cp ./backups backend:/home/frappe/frappe-bench/sites/frontend/private/
B=/home/frappe/frappe-bench/sites/frontend/private/backups
docker compose exec backend bench --site frontend restore \
  $B/20261029_020000-dokompany_fr-database.sql.gz \
  --with-public-files $B/20261029_020000-dokompany_fr-files.tar \
  --with-private-files $B/20261029_020000-dokompany_fr-private-files.tar
docker compose exec backend bench --site frontend set-config encryption_key "<clé de l'ancien site>"
docker compose exec backend bench --site frontend migrate

Si restore demande le mot de passe root de MariaDB, saisissez la valeur MYSQL_ROOT_PASSWORD du service db de votre fichier Compose. Changez cette valeur par défaut avant la mise en production.

migrate exécute les patchs qui passent la base de la v4 à la v5. Lisez sa sortie jusqu'au bout. Une erreur de patch arrête la migration : notez le message complet.

Basculer le domaine

Configurez Nginx et le certificat sur la nouvelle machine (voir Installation Docker), puis changez l'enregistrement DNS du domaine vers la nouvelle machine. Arrêtez l'ancien site seulement après vos vérifications.

Chemin en place : mettre à jour le bench existant

Ce chemin modifie l'environnement Python du bench en place. Faites une sauvegarde complète et, si possible, un instantané de la machine avant de commencer. Ce guide concerne les installations sous Ubuntu.

Installer Node.js 24

Utilisez nvm ou le dépôt NodeSource :

wget -qO- https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
node --version

Installer Python 3.14

Installez Python 3.14 à côté du Python du système, sans le remplacer. Sinon, des outils comme apt peuvent cesser de fonctionner. Ne changez donc pas la commande python3 par défaut (pas de update-alternatives).

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.14 python3.14-dev python3.14-venv libmariadb-dev
python3.14 -V

Mettez ensuite à jour docli, l'outil qui fournit la commande bench : pip install dokos-cli --upgrade.

Créer un bench en Python 3.14

bench migrate-env python3.14 échoue tant que Dodock est en v4, avec un message du type Package 'frappe' requires a different Python: 3.14.x not in '<3.13,>=3.10'. La v4 n'est pas compatible avec Python 3.14. Créez donc un nouveau bench :

bench init ~/dokos-bench-v5 --python python3.14 --frappe-branch v5
cd ~/dokos-bench-v5
bench get-app https://gitlab.com/dokos/dokos --branch v5    # puis hrms, payments, webshop… selon ~/dokos-bench/sites/apps.txt
mv ~/dokos-bench/sites/dokompany.fr sites/

Ajoutez au nouveau bench, en branche v5, chaque application listée dans ~/dokos-bench/sites/apps.txt.

Ajouter les applications sorties de Dodock

Plusieurs modules sont sortis de Dodock en v5. Si votre site les utilise, ajoutez leur application au bench avec bench get-app <dépôt>, en choisissant la branche compatible avec Dodock v5 indiquée dans le dépôt :

Installez ensuite chaque application ajoutée sur le site : bench --site dokompany.fr install-app <application>. Le nom de l'application est celui de son dossier dans apps/.

Mettre à jour et passer en production

bench setup production <utilisateur>
bench update

Voir aussi Mettre à jour Dokos. Si ModuleNotFoundError: No module named 'virtualenv' apparaît, lancez pip install virtualenv. Si Python ou apt-get ne fonctionne plus, le Python du système a été remplacé : réinstallez-le avant de continuer.

Changements à connaître en v5

• La navigation utilise une barre latérale persistante, basée sur le type de document Workspace Sidebar.
• Les vues de liste sont triées par défaut par date de création (creation) au lieu de la date de modification.
• La Console système est réservée au rôle Administrateur.
• Le code d'un Pays doit être un code ISO 3166 alpha-2 valide.
• L'application E-transactions remplace l'application OCR. Si vous utilisiez OCR, installez E-transactions (bench get-app https://gitlab.com/dokos/etransactions --branch v5, puis install-app etransactions) : Dokos reprend vos paramètres. Vous pouvez ensuite désinstaller OCR.

Exemple

Dokompany utilise Dokos v4 sur une machine Ubuntu 22.04 avec Dokos, HRMS, Payments et Webshop. L'administrateur loue une nouvelle machine, installe Docker et le fichier Compose par défaut. Il restaure la sauvegarde du vendredi soir, copie la clé encryption_key, lance migrate, puis bascule le DNS de dokompany.fr le samedi matin.

Vérifier

• Aide > À propos affiche Dodock et Dokos en version 5.
• Un compte email s'ouvre sans erreur de déchiffrement.
• Suivez la liste de contrôle après migration.

Revenir en arrière

• Chemin Docker : remettez l'enregistrement DNS vers l'ancien serveur. Les saisies faites sur la v5 entre-temps sont perdues.
• Chemin en place : restaurez l'instantané de la machine, ou la sauvegarde sur un bench v4.

Problèmes fréquents