Migrer vers la version 4 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 4 de Dokos nécessite Python 3.10 ou Python 3.11 et NodeJS 18 pour fonctionner.
Si vous avez précédemment installé Dokos v3, une mise à jour de certains paquets logiciels et une migration du dossier bench est nécessaire avant d'installer Dokos v4.

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

Prérequis (Node 18, Python 3.10)

Installer NodeJS 18

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

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

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

Installer Python 3.10

Il faut installer Python 3.10 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.10 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.10
sudo apt-get install python3.10-dev
sudo apt-get install python3.10-distutils

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

sudo update-alternatives --config python3

python3 -V

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

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

pip install dokos-cli --upgrade

Finaliser la migration

Migration de l'environnement virtuel de votre bench

Une fois Python 3.10 et Node 18 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.10, vous pouvez passer cette étape..

bench migrate-env python3.10

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 Dokos sont désormais publiés dans des modules séparés. Si vous utilisez certaines de leurs fonctionnalités, commencez par les ajouter dans votre bench.

Webhsop

Cette application est à installer uniquement si vous utilisez les fonctionnalités eCommerce de Dokos.

bench get-app https://gitlab.com/dokos/webshop --branch v4

Montée de version de Dodock/Dokos

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

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

Installation des nouvelles applications sur votre site

Installez les nouvelles applications sur votre site

bench install-app webshop

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 v4.

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.10.

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.10 avec la commande bench init bench-nouveau --python python3.10

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 (Python 3.4 sous Ubuntu 18) 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/1200793#1200793

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.10, à couper/copier le dossier contenant les éléments de votre site dans ce nouveau bench et à lancer la mise à jour dans ce nouveau bench.

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

Activer les scripts serveur si besoin

Pour des raisons de sécurité, les scripts serveur sont maintenant 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.

Migrer vers la version 3 de Dokos

Si vous utilisez Dokos v2 en auto-hébergement, certaines étapes sont requises avant de mettre à jour votre installation vers la version 3 de Dokos.

Migrer depuis ERPNext