DocDB

Guide d'installation et de désinstallation du module DocDB

Installation

Pré-requis

Si vous avez déjà pratiqué la ligne de commande, vous devriez réussir sans difficulté (vous ne devriez pas y passer plus d'une dizaine de minutes). Vous avez mené à bien l'installation de Dolibarr, celle de docDB ne devrait pas être un problème pour vous.
Ceci étant, en cas de problème, vous aurez besoin d'un minimum d'expérience d'intégrateur.
Sachez que les commandes peuvent être testées avant d'être réalisées effectivement.
DANS TOUS LES CAS : Sauvegardez impérativement dossier Dolibarr, documents, base de données AVANT de commencer.

DocDB est testé dans les contextes figurant ci-après, mais cela ne veut pas dire qu'il ne fonctionne pas sur d'autres versions d'autres systèmes. Il est développé avec des fonctions courantes. Si vous maîtrisez suffisamment les composants de Dolibarr, rien ne vous empêche d'essayer, et si tout fonctionne parfaitement sur le protocole de tests, il serait improbable de récupérer des erreurs par ailleurs.
Si vous avez développé un module ou un programme spécifique, consultez la section réservée à ce sujet un peu plus loin dans ce document.

Dolibarr Version 17.0.0
Systèmes de base de données Mysql ou MariaDB, toutes versions utilisées par Dolibarr
PostgresSQL non supporté
Systèmes d'exploitation Linux toutes versions supportant Python 3
Windows toutes versions à partir de la 10
(Vous devrez installer une version 3 standard de python. Précisons que la version adaptée par Microsoft risque de poser un grand nombre de problèmes)
Python Version 3.9 et ultérieures
Python mysql.connector Version 8.0.32 et ultérieures

Mode opératoire

Le module docDB est préférable car il offre un cadre documentaire, mais il n'est pas strictement indispensable. C'est-à-dire que vous pouvez copier les programmes par un autre moyen, et les activer sans que le module soit installé.
L'installation est réalisée dans un premier temps en modifiant les scripts de Dolibarr, puis dans un second temps en copiant les documents dans la base de données.

> Installation de python

Pour Linux, python est inclus dans le système.
Vérification :
$ python3 -V
Python 3.9.2
Pour Windows, utilisez l'installeur automatique de la dernière version récupérée sur www.python.org/downloads/, une affaire de quelques minutes. N'oubliez pas d'inclure python dans le PATH (indiqué environnement Windows dans l'installeur.
Vérification :
$ py -V
Python 3.11.3
Si vous obtenez un numéro de version différent, cela n'a pas d'importance pourvu qu'il s'agisse bien d'une version 3 (les scripts ne sont pas compatibles avec la version 2, qui est arrêtée à ce jour).
Microsoft fournit python, mais c'est une version modifiée, non recommandée par votre serviteur. Ne l'utilisez pas, elle n'est pas à jour et apporte des quantités de problèmes.
Pour lancer la commande, après installation de la version officielle, utilisez py à la place de python3. Ceci vaut pour tout ce qui suit.

> Installation de mysql connector

Sous Linux, lancez l'installation du module et confirmez.
$ apt install python3-pip
$ pip3 install mysql-connector-python
Pour vérifier que l'installation est effective :
$ python3
>>> import mysql.connector
Sous Windows, téléchargez l'installeur depuis dev.mysql.com/downloads/connector/python/ et installez-le. Vous devrez aussi installer le paquet VC redistributable de Microsoft.
$ py
>>> import mysql.connector

> Installation de php

Normalement, php est installé puisque Dolibarr fonctionne. La commande de migration des fichiers a besoin de php pour trouver les caractéristiques de certains documents (python pourrait le faire, mais les résultats qu'il obtiendrait pourraient se trouver légèrement différents).
Dans le fichier de configuration php.ini (par exemple dans /etc/php/7.4/apache2/php.ini), l'extension exif (extension=exif) doit être activée, ce qui est normalement le cas. À modifier donc uniquement en cas de plantage.

> Installation du paquet docDB

Récupérez le paquet sur le Dolistore, et suivez la procédure standard d'installation du paquet.

> Arrêt du serveur web

Dans le principe, on va modifier Dolibarr, et il n'est pas pertinent que celui-ci continue à fonctionner. Un arrêt du serveur web est donc impératif. Par contre, la base de données peut et doit continuer à fonctionner.
Dans un terminal :
# systemctl stop apache2
Avec une fenêtre de commande lancée en mode administrateur) :
> net stop Apache2.4
Avant de continuer, vérifiez par acquis de conscience que Dolibarr est inaccessible.

> Positionnement dans le bon dossier

Imaginons que Dolibarr soit installé dans le dossier /var/www/dolibarr/htdocs (nous utiliserons cet exemple par la suite). Vous devez vous placer dans le dossier install du module. Pour Windows, les caractères / doivent être remplacés par des \. Nous prendrons par ailleurs le répertoire \Apache24\htdocs\dolibarr
Notez que les dossiers à l'extérieur de htdocs ne sont pas pris en compte. C'est une limitation qui ne devrait pas vous gêner.
$ cd /var/www/dolibarr/htdocs
$ cd custom/docdb/install
$ cd \Apache24\htdocs\dolibarr
$ cd custom\docdb\install
Si la 2ème commande ne fonctionne pas, c'est qu'à priori le module n'est pas installé.

> Conversion des scripts Dolibarr

$ python3 docDBmigrateScripts.py --dry-run --dolibarrDir=/var/www/dolibarr/htdocs
Le switch -X utf8 est nécessaire si le jeu de caractères par défaut n'est pas unicode (c'est ce qui se produit le plus souvent).
$ py -X utf8 docDBmigrateScripts.py --dry-run --dolibarrDir=\Apache24\htdocs\dolibarr
Vous demandez l'exécution de docDBmigrateScripts.py, avec un switch --dry-run, en indiquant l'emplacement de Dolibarr /var/www/dolibarr/htdocs (ou \Apache24\htdocs\dolibarr). Le programme vérifie qu'il trouve bien Dolibarr à cet endroit, que le dossier des documents existe, et que le paramétrage des fichiers sources est correct. Puis il demande une confirmation :
$ python3 docDBmigrateScripts.py --dry-run --dolibarrDir=/var/www/dolibarr/htdocs
-- checking /var/www/dolibarr/htdocs
version Dolibarr 16.0.5 found at the right place
-- checking configuration file /var/www/dolibarr/htdocs/conf/conf.php
configuration file /var/www/dolibarr/htdocs/conf/conf.php is good
-- checking documents path /var/dolibarr/documents
directory /var/dolibarr/documents exists (must be writable, I did not check it)
-- checking source files referenced in ./scriptFiles/16.0.5
source files referenced in ./scriptFiles/16.0.5 are good
>> please confirm (y/N) I must migrate this directory : /var/www/dolibarr/htdocs
NB : this is a dry run, I am just showing what could happen
Une confirmation est demandée (tapez y). De toutes façon, comme vous avez indiqué --dry-run, rien ne sera modifié.
Attention ! Si vous avez modifié certains sources Dolibarr (leur emplacement est indiqué à l'étape --checking sources files referenced), ou si la version de ceux-ci est différente d'une version attendue, ceci ne fonctionnera pas et le programme n'ira pas plus loin. Il vous affichera quelque chose du style :
some source file(s) referenced in ./scriptFiles/16.0.5 are not OK
nothing was done, see you later
Si vous avez confirmé, le programme affiche :
-- migrating /var/www/dolibarr/htdocs
../scripts/user/sync_groups_ldap2dolibarr.php ['fgets']
../scripts/user/sync_users_ldap2dolibarr.php ['fgets']
../scripts/user/migrate_picture_path.php ['is_dir', 'opendir', 'readdir']
../scripts/website/migrate-news-joomla2dolibarr.php ['file_get_contents']
../scripts/product/migrate_picture_path.php ['is_dir', 'opendir', 'readdir']
  ...
../htdocs/hrm/class/skillrank.class.php ['file_exists', 'rename']
../htdocs/hrm/class/skill.class.php ['file_exists', 'rename']
../htdocs/hrm/class/position.class.php ['file_exists', 'rename']
-- updating configuration file
-- updating source files referenced in ./scriptFiles/16.0.5
-- copying filebypass.php
migration should not act as expected (578 files, 3589 changes ; would migrate but 574/3558 expected)
Il affiche la liste des nombreux scripts à modifier, ainsi que les fonctions php à modifier entre crochets. Dans l'exemple ci-dessous, la modification des fonctions 'is_dir', 'opendir', 'readdir' est anticipée dans le script migrate_picture_path.php.
Notez la phrase migration should not act as expected. Elle signifie que le nombre de script n'est pas celui attendu. Ceci se produit quand un module (ou plus) a été installé. Le programme ne connaît que le nombre de scripts standard, c'est pourquoi il signale une différence. Elle est sans importance, le travail va être fait, pourvu qu'on enlève --dry-run dans notre commande. Allons-y :
$ python3 docDBmigrateScripts.py --dolibarrDir=/var/www/dolibarr/htdocs
$ py -X utf8 docDBmigrateScripts.py --dolibarrDir=\Apache24\htdocs\dolibarr
Dans notre exemple, on obtient cette fois
migration not done as expected (578 files, 3589 changes ; migrated but 574/3558 expected)
Le mot important est migrated, il veut dire que le travail a été fait.
À ce stade, si on consultait Dolibarr, on aurait l'impression que nos documents ont disparu. Pas d'inquiétude, ils seraient toujours au même endroit, mais comme Dolibarr consulterait la base de donnée au lieu du système de fichiers, et que celle-ci ne contiendrait aucun document, il nous le signalerait avec des erreurs.

> Conversion des documents

La méthode pour convertir les documents est analogue à celle qui est utilisée pour les scripts php. Une commande à lancer (docDBmigrateFiles.py cette fois), avec des vérifications, une confirmation, et un résultat. Essayons avec --dry-run. Notez que c'est bien le répertoire de Dolibarr que l'on donne en argument, et pas celui des documents de Dolibarr. On comprend bien qu'il faut un accès au fichier de configuration pour se connecter à la base de donnée.
$ python3 docDBmigrateFiles.py --dry-run --dolibarrDir=/var/www/dolibarr/htdocs
Si php n'est pas dans le path, l'utilisation du switch --phpdir est nécessaire.
$ py -X utf8 docDBmigrateFiles.py --dry-run --dolibarrDir=\Apache24\htdocs\dolibarr --phpdir=\php
Le résultat avec la demande de confirmation :
-- checking /var/www/dolibarr/htdocs
-- checking configuration file /var/www/dolibarr/htdocs/conf/conf.php
configuration file /var/www/dolibarr/htdocs/conf/conf.php is good
-- checking documents path /var/dolibarr/documents
directory /var/dolibarr/documents exists
-- checking connection on database docDB16
connected on database docDB16, reading documents information
15 documents referenced in the database, thumbs included
>> please confirm (y/N) I must migrate this directory : /var/www/dolibarr/htdocs
NB : this is a dry run, I am just showing what could happen
Le programme indique dans notre cas 15 documents à migrer. Notez qu'un Dolibarr venant juste d'être installé ne contient aucun document (dans ce cas le message sera : 0 documents referenced in the database).
On confirme, pour voir.
-- migrating documents
/facture/FA2304-0001/FA2304-0001-02 - west run - part 1 - dscf3650.jpg
/facture/FA2304-0001/FA2304-0001-078E-Auguste-Herbin-moulin-o.jpg
 ...
/mycompany/logos/thumbs/apia-asso-logo-carre_mini.png
/mycompany/logos/thumbs/apia-asso-logo-carre_small.png
/mycompany/logos/thumbs/apia-asso-logo_mini.png
/mycompany/logos/thumbs/apia-asso-logo_small.png
documents migration should act as expected
La dernière ligne nous dit que tout devrait bien se passer. Bien entendu, le --dry-run n'est absolument pas obligatoire, et on aurait très bien passer la commande directement.
$ python3 docDBmigrateFiles.py --dolibarrDir=/var/www/dolibarr/htdocs
$ py -X utf8 docDBmigrateFiles.py --dolibarrDir=\Apache24\htdocs\dolibarr --phpdir=\php
avec comme résultat :
-- checking /var/www/dolibarr/htdocs
-- checking configuration file /var/www/dolibarr/htdocs/conf/conf.php
configuration file /var/www/dolibarr/htdocs/conf/conf.php is good
-- checking documents path /var/dolibarr/documents
directory /var/dolibarr/documents exists
-- checking connection on database docDB16
connected on database docDB16, reading documents information
15 documents referenced in the database, thumbs included
>> please confirm (y/N) I must migrate this directory : /var/www/dolibarr/htdocs
y
-- migrating documents
/facture/FA2304-0001/FA2304-0001-02 - west run - part 1 - dscf3650.jpg
/facture/FA2304-0001/FA2304-0001-078E-Auguste-Herbin-moulin-o.jpg
/facture/FA2304-0001/FA2304-0001.pdf
  ...
/mycompany/logos/thumbs/apia-asso-logo-carre_small.png
/mycompany/logos/thumbs/apia-asso-logo_mini.png
/mycompany/logos/thumbs/apia-asso-logo_small.png
-- creating directories
documents migration done, you can move some /var/dolibarr/documents subdirectories elsewhere to keep them safe, but please don't move the following (because Dolibarr need them to work properly) :
    /api/temp
    dolibarr.log
    install.lock
Cette fois la migration est faite (documents migration done). Le programme propose de déplacer le dossier des documents. Cela vous confirmera lors du fonctionnement de Dolibarr que l'accès se fait bien dans la base données, et pas à l'endroit habituel où ils ne sont plus. Quoi qu'il en soit, veillez à conserver les dossiers et fichiers indiqués au bon endroit, sans quoi le fontionnement de Dolibarr serait fortement perturbé.
Par ailleurs, il est question de creating directories, de quoi s'agit-il puisque les documents sont maintenant dans une base de données ? C'est simplement que docDB émule un comportement standard de fichiers, et qu'il a besoin d'une table (llx_doc_directory) où se trouvent les noms des dossiers supposés contenir les documents. En réalité ceux-ci sont dans une autre table (llx_doc_data) qui joue le rôle de conteneur. Vous pouvez vous connecter sur mysql et taper les requêtes vous permettant de voir de quoi il retourne :
MariaDB [docDB16]> select * from llx_doc_directory;
+-------+-----------------------------+
| rowid | path_name                   |
+-------+-----------------------------+
|     1 | /admin                      |
|     2 | /admin/temp                 |
|     3 | /admin/temp/                |
  ...
 MariaDB [docDB16]> select rowid,path_name,filemtime,octet_length(datablob) as filesize,octet_length(exif_data) as exif_data,
octet_length(imagesize) as imagesize from llx_doc_data order by rowid;
+-------+-----------------------------------------------------------------------------------------------------+---------------------+----------+-----------+-----------+
| rowid | path_name                                                                                           | filemtime           | filesize | exif_data | imagesize |
+-------+-----------------------------------------------------------------------------------------------------+---------------------+----------+-----------+-----------+
|     1 | /facture/FA2304-0001/FA2304-0001-02 - west run - part 1 - dscf3650.jpg                              | 2023-04-08 11:01:07 |  1813708 |      4184 |       137 |
|     2 | /facture/FA2304-0001/FA2304-0001-078E-Auguste-Herbin-moulin-o.jpg                                   | 2023-04-08 11:01:17 |   205915 |       783 |       133 |
|     3 | /facture/FA2304-0001/FA2304-0001.pdf                                                                | 2023-04-11 11:16:27 |    45379 |         4 |         4 |
  ...
Bien entendu, les parties utiles des documents ne sont pas affichées ici.
Également, si Dolibarr vient d'être installé, vous obtenez après chacune des deux requêtes : Empty set ou Table doesn't exist.
Pour plus d'explication sur le fonctionnement de ces tables, rendez-vous sur le wiki Dolibarr.

> Ping

S'il-vous-plaît, dites-moi que vous avez installé docDB. Cela me donnera une idée du nombre de personnes intéressées par ce module.
$ python3 docDBping.py
$ py -X docDBping.py

> Redémarrage du serveur web

Une simple commande :
# systemctl start apache2
> net start Apache2.4
Voilà, c'est fait.
N'oubliez pas d'adapter votre procédure de sauvegardes. Il suffit de retirer la partie concernant le répertoire qui contenait les documents. Pour la base de données, rien ne change, à ceci près que la sauvegarde sera plus volumineuse et plus longue.
Un dernier commentaire : l'effort nécessaire pour passer sous Linux n'est pas si important, et le retour sur investissement est tellement rapide !

Revenir à l'état standard (désinstallation)

Imaginons qu'après une période d'essai, la solution docDB ne vous convienne pas. Disons que vous avez changé d'avis, vous aimeriez revenir à l'état standard. Entre parenthèse, j'aimerais bien savoir pourquoi, n'hésitez pas à me le dire :-)
Ceci est possible, il suffit de rejouer exactement la même procédure, mais en ajoutant --reverse aux commandes docDBmigrateScripts.py et docDBmigrateFiles.py. Cela vous serait utile si les utilisateurs de Dolibarr ont ajouté des données, auquel cas les sauvegardes que vous avez faites avant la migration ne seraient pas à jour.
$ python3 docDBmigrateScripts.py --reverse --dolibarrDir=/var/www/dolibarr/htdocs
  ...
$ python3 docDBmigrateFiles.py --reverse --dolibarrDir=/var/www/dolibarr/htdocs
  ...
$ py -X utf8 docDBmigrateScripts.py --reverse --dolibarrDir=\Apache24\htdocs\dolibarr
  ...
$ py -X utf8 docDBmigrateFiles.py --reverse --dolibarrDir=\Apache24\htdocs\dolibarr --phpdir=\php
  ...
Il va de soi qu'on peut utiliser --dry-run dans cette opération également.
Vous aurez arrêté le serveur web avant opération, et vous devrez sans doute modifier les droits d'accès des documents après opération (le user avec lequel vous procédez ne donnera sans doute pas l'accès au user de Apache). Les commandes nécessaires vous seront proposées en fin d'opération. Et n'oubliez pas de supprimer les tables llx_doc_directory et llx_doc_data dans la base de données après opération.
documents REVERSE migration done
take care about access rights of your documents ! If www-data is your web server user, I suggest :
    chown -R www-data:www-data /var/dolibarr/documents
    chmod u+w -R /var/dolibarr/documents
You should also clean up your database docDB16 :
    drop table llx_doc_directory;
    drop table llx_doc_data;

En cas de mise-à-jour de Dolibarr

Que se passe-t-il dans ce cas ? Hé bien c'est très simple : vous devez mettre à jour vos scripts Dolibarr comme d'habitude dans le dossier sur serveur web, et avant de faire fonctionner (c'est-à-dire avant de lancer la mise-à-jour dans Dolibarr), repassez la commande docDBmigrateScripts.py. Sans quoi Dolibarr ne trouvera pas ses documents. Précisons que docDBmigrateScripts.py peut être rejouée un grand nombre de fois sans inconvénient. Si elle ne trouve pas de script php à migrer, elle ne fera tout simplement rien. C'est ce qui se produit si on la passe deux fois de suite.
Il existe tout de même une nuance : certains scripts particuliers (ceux qui se trouvent dans le dossier install/scriptFiles vont être recopiés systématiquement. Il s'agit de ceux dont la migration automatique était trop hasardeuse à programmer. Aucun impact s'ils n'ont pas changé dans la nouvelle version de Dolibarr. Sinon, il est préférable d'attendre la version de DocDB qui prendra en compte cette nouvelle version de Dolibarr.
Par contre, docDBmigrateFiles.py est à prendre avec précaution car il écrase le contenu des documents en base de données. Si des utilisateurs ont chargé ou généré des documents, ceux-ci risquent d'être perdus. L'utilisation de cette commande est totalement inutile et presque certainement néfaste une fois que vous avez commencé à utiliser Dolibarr avec docDB.

Si vous ajoutez un module Dolibarr

Si votre module est installé dans Dolibarr avant l'installation de DocDB, rien de spécial à faire. Le programme de conversion prendra sous son aile les scripts supplémentaires et convertira les fonctions concernées par les documents.
Si vous installez votre module après coup, procédez comme d'habitude mais repassez le programme de conversion, en dry run dans un premier temps. Il vous indiquera les scripts non convertis et les convertira si vous confirmez.
Si votre module ne gère pas spécialement les documents, il ne sera pas impacté. Dans le cas contraire, testez soigneusement avant de mettre en production.