Documentation
Administration

Migrer vers la version 5 de Dokos

Si vous utilisez Dokos v4 en auto-hébergement, certaines étapes sont requises avant de mettre à jour votre installation vers la version 5 de Dokos.
Si vous souhaitez installer Dokos pour la première fois, consultez le guide d'installation rapide plutôt que ce guide de migration.

La version 5 de Dokos nécessite Python 3.14+ et NodeJS 24+ pour fonctionner. Si vous utilisez actuellement Dokos v4, une mise à jour de certains paquets logiciels et une migration du dossier bench est nécessaire avant d'installer Dokos v5.

📄 Ce guide est destiné aux installations de Dokos auto-hébergées sous Ubuntu.

N'oubliez jamais de sauvegarder avant d'effectuer n'importe quelle opération de migration.



Prérequis (Node 24, Python 3.14)

Installer NodeJS 24

Pour installer NodeJS 24 sur Ubuntu, vous pouvez utiliser le gestionnaire de versions nvm, ou alternativement utiliser les commandes suivantes :

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

Puis vérifiez l'installation avec node --version.

Installer Python 3.14

Il faut installer Python 3.14 sans remplacer la version de Python installée par défaut avec Ubuntu, car cela pourrait interférer avec le fonctionnement de certains outils comme apt.

Pour installer Python 3.14 sur Ubuntu, il est recommandé d'utiliser le paquet deadsnakes/ppa. L'installation peut s'effectuer comme ci-dessous :

sudo add-apt-repository ppa:deadsnakes/ppa

sudo apt-get update

sudo apt-get install python3.14
sudo apt-get install python3.14-dev
sudo apt-get install python3.14-distutils
sudo apt-get install python3.14-venv
sudo apt-get install libmariadb-dev

sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.14 1

sudo update-alternatives --config python3

python3 -V

Vous pouvez vérifier que Python 3.14 est installé avec python3 -V, avant de poursuivre comme suit :

curl -sS https://bootstrap.pypa.io/get-pip.py | python3.14

pip install dokos-cli --upgrade

Changements importants dans Dodock v5

Nouvelles applications séparées de Dodock

Dans la version 5, plusieurs modules ont été extraits de Dodock/Frappe et publiés en tant qu'applications indépendantes. Si vous utilisez leurs fonctionnalités, vous devrez les installer séparément :

  • Blog : gestion des articles de blog
  • Energy Points : système de points d'énergie et gamification
  • Newsletter : gestion des newsletters
  • Backup Integrations : intégrations pour les sauvegardes (S3, etc.)

Nouvelle application eTransactions

L'application eTransactions (gitlab.com/dokos/etransactions) est une nouvelle application disponible en V5 permettant de lire les factures électroniques aux formats UBL et CII.

Super PDP a annoncé sa connexion avec AFNOR. Les développements pour se connecter à la Plateforme Agréée vont pouvoir démarrer prochainement.
L'application OCR reste disponible en V5. eTransactions a vocation à la remplacer à terme, mais les développements sont encore en cours. Il n'est pas nécessaire de désinstaller OCR lors de la migration vers V5.
# Récupérer la nouvelle application eTransactions
bench get-app https://gitlab.com/dokos/etransactions --branch v5

# Installer eTransactions sur votre site
bench --site {nom_du_site} install-app etransactions

Autres changements notables

  • La navigation utilise désormais une barre latérale persistante basée sur le doctype Workspace Sidebar. Les espaces de travail standard modifiés seront réinitialisés lors de la migration.
  • Le tri par défaut des vues de liste est maintenant par creation au lieu de modified.
  • L'accès à la console système est désormais restreint aux Administrateurs par défaut.
  • Les champs Country requièrent maintenant des codes ISO 3166 ALPHA-2 valides.

Finaliser la migration

Migration de l'environnement virtuel de votre bench

Une fois Python 3.14 et Node 24 correctement installés, vous pouvez poursuivre avec la migration du dossier de bench vers la nouvelle version de Python.

Si votre bench est déjà sous Python 3.14, vous pouvez passer cette étape.
bench migrate-env python3.14
Chaque bench est un environnement virtuel Python séparé des autres environnements virtuels. Seul dokos-cli utilise la version de Python par défaut du système.

Ajout des nouvelles applications

Certains modules de Dodock sont désormais publiés dans des applications séparées. Si vous utilisez certaines de leurs fonctionnalités, commencez par les ajouter dans votre bench.

Blog

bench get-app https://github.com/frappe/blog --branch version-16

Energy Points

bench get-app https://github.com/frappe/eps --branch version-16

Newsletter

bench get-app https://github.com/frappe/newsletter --branch version-16

Backup Integrations

bench get-app https://github.com/frappe/offsite_backups --branch version-16

Montée de version de Dodock/Dokos

Après la récupération des nouvelles applications, changez de branche pour passer sur la version 5 de Dodock/Dokos.

bench switch-to-branch v5 frappe erpnext hrms payments --upgrade

Installation des nouvelles applications sur votre site

Installez les nouvelles applications souhaitées sur votre site :

bench --site {nom_du_site} install-app blog
bench --site {nom_du_site} install-app energy_points
bench --site {nom_du_site} install-app newsletter
bench --site {nom_du_site} install-app backup_integrations

Relancez une mise à jour

Enfin, mettez à jour Dokos/Dodock normalement.

bench update --reset
Si l'installation s'est passée correctement, vous pouvez désormais profiter des nouvelles fonctionnalités de Dokos v5.



Dépannage

Vérifiez que les paquets prérequis sont correctement installés avec les commandes suivantes :
python3 --version
pip --version
node --version
yarn --version
docli --version / bench --version

La migration du bench échoue

Si les prérequis sont correctement installés, il est normalement possible de migrer un bench d'une version de Python à une autre avec la commande bench migrate-env python3.14.

Si jamais cela ne fonctionne pas, il peut être plus simple de créer un nouveau bench puis d'y déplacer un site depuis l'ancien bench.

Tout d'abord, créez un nouveau bench sous Python 3.14 avec la commande bench init bench-nouveau --python python3.14

Déplacez-y le dossier contenant votre site dans ce nouveau bench mv ~/bench-ancien/sites/mon_site ~/bench-nouveau/sites/, puis exécutez la commande bench setup production {votre utilisateur} && bench update dans le nouveau bench.

Vous aurez peut-être besoin d'installer de nouveau les applications tierces que vous avez pu installer. Vous pouvez consulter la liste de ces applications avec la commande cat ~/bench-ancien/sites/apps.txt.

Pour toute question ou demande d'aide, vous pouvez vous rendre sur le forum de la communauté.

Python/apt-get ne fonctionne plus

Si jamais votre installation globale de Python ne fonctionne plus, vous pouvez réinstaller la version système de Python en suivant ce lien : https://askubuntu.com/questions/1196401/how-to-fix-python3-after-messing-it-up/1196790#1196790

ModuleNotFoundError: No module named virtualenv

Si cette erreur se produit, il suffit de reinstaller virtualenv avec la commande pip install virtualenv.

Si vous rencontrez trop de difficultés à migrer votre bench existant, n'hésitez pas à créer un nouveau bench sous python3.14, à couper/copier le dossier contenant les éléments de votre site dans ce nouveau bench et à lancer la mise à jour dans ce nouveau bench.

Activer les scripts serveur si besoin

Pour des raisons de sécurité, les scripts serveur sont désactivés par défaut. Pour les activer, il faut configurer la clé server_script_enabled dans les paramètres du bench avec bench set-config -g server_script_enabled 1. Il n'est pas possible d'activer les scripts serveur au niveau d'un site.