Guía de instalación y desinstalación del módulo DocDB

Instalación

Requisitos previos
Procedimiento

Instalación de Python
Instalación del conector MySQL
Instalación de PHP
Detener el servidor web
Ubicación en la carpeta correcta
Conversión de los scripts de Dolibarr
Conversión de los documentos
Reinicio del servidor web

Volver al estado estándar (desinstalación)
En caso de actualización de Dolibarr
Si se agrega un módulo Dolibarr

Instalación

Requisitos previos

Si ya tienes experiencia con la línea de comandos, deberías tener éxito sin dificultad (no deberías tardar más de diez minutos). Si has instalado Dolibarr correctamente, la instalación de DocDB no debería ser un problema para ti.
Sin embargo, en caso de problemas, necesitarás tener experiencia mínima como integrador.
Ten en cuenta que los comandos se pueden probar antes de ejecutarlos.
EN TODOS LOS CASOS: Haz una copia de seguridad del directorio de Dolibarr, los documentos y la base de datos ANTES de comenzar.

DocDB se ha probado en los siguientes contextos, pero esto no significa que no funcione en otras versiones de otros sistemas. Está desarrollado utilizando funciones comunes. Si tienes suficiente conocimiento de los componentes de Dolibarr, puedes probarlo, y si todo funciona perfectamente en el protocolo de pruebas, es poco probable que encuentres errores en otros casos.
Si has desarrollado un módulo o programa específico, consulta la sección correspondiente más adelante en este documento.

Dolibarr	Versión 17.0.0
Sistemas de bases de datos	Mysql o MariaDB, todas las versiones utilizadas por Dolibarr PostgresSQL no es compatible
Sistemas operativos	Linux todas las versiones compatibles con Python 3 Windows todas las versiones a partir de la 10 (Deberás instalar una versión 3 estándar de Python. Ten en cuenta que la versión adaptada por Microsoft puede causar muchos problemas)
Python	Versión 3.9 y posteriores
Python mysql.connector	Versión 8.0.32 y posteriores

Procedimiento

El módulo DocDB es preferible porque proporciona un marco documental, pero no es estrictamente necesario. Esto significa que puedes copiar los programas de otra manera y activarlos sin tener instalado el módulo.
La instalación se realiza en dos pasos: primero modificando los scripts de Dolibarr y luego copiando los documentos en la base de datos.

> Instalación de Python

Para Linux, Python ya está incluido en el sistema.
Verificación:

$ python3 -V
Python 3.9.2

Para Windows, utiliza el instalador automático de la última versión disponible en www.python.org/downloads/, solo tomará unos minutos. No olvides incluir Python en el PATH (marcado como entorno de Windows en el instalador).
Verificación :

$ py -V
Python 3.11.3

Si obtienes un número de versión diferente, no importa siempre y cuando sea una versión 3 (los scripts no son compatibles con la versión 2, que está obsoleta en la actualidad).
Microsoft proporciona Python, pero es una versión modificada y no es recomendada. No la uses, no está actualizada y presenta muchos problemas.
Después de instalar la versión oficial, utiliza py en lugar de python3 para ejecutar el comando. Esto se aplica a todo lo siguiente.

> Instalación de mysql connector

En Linux, inicia la instalación del módulo y confirma.

$ apt install python3-pip
$ pip3 install mysql-connector-python

Para verificar que la instalación se realizó correctamente:

$ python3
>>> import mysql.connector

En Windows, descarga el instalador desde dev.mysql.com/downloads/connector/python/ e instálalo. También debes instalar el paquete VC redistributable de Microsoft.

$ py
>>> import mysql.connector

> Instalación de php

Normalmente, php ya está instalado ya que Dolibarr funciona. El comando de migración de archivos requiere php para obtener las características de ciertos documentos (Python podría hacerlo, pero los resultados podrían ser ligeramente diferentes).
En el archivo de configuración php.ini (por ejemplo, en /etc/php/7.4/apache2/php.ini), la extensión exif (extension=exif) debe estar habilitada, lo cual es normalmente el caso. Solo se debe modificar en caso de fallos.

> Instalación del paquete docDB

Obtén el paquete desde el Dolistore y sigue el procedimiento estándar de instalación del paquete.

> Detener el servidor web

En principio, vamos a modificar Dolibarr, y no es relevante que siga funcionando. Por lo tanto, es imperativo detener el servidor web. Sin embargo, la base de datos puede y debe seguir funcionando.
En una terminal:

# systemctl stop apache2

Con una ventana de comandos abierta en modo de administrador:

> net stop Apache2.4

Antes de continuar, verifica por precaución que Dolibarr no es accesible.

> Ubicación en la carpeta correcta

Supongamos que Dolibarr está instalado en la carpeta /var/www/dolibarr/htdocs (utilizaremos este ejemplo más adelante). Debes ubicarte en la carpeta install del módulo. En Windows, los caracteres / deben reemplazarse por \. Además, usaremos el directorio \Apache24\htdocs\dolibarr
Ten en cuenta que las carpetas fuera de htdocs no se toman en cuenta. Es una limitación que no debería afectarte.

$ cd /var/www/dolibarr/htdocs
$ cd custom/docdb/install

$ cd \Apache24\htdocs\dolibarr
$ cd custom\docdb\install

Si el segundo comando no funciona, probablemente el módulo no está instalado.

> Conversión de los scripts de Dolibarr

$ python3 docDBmigrateScripts.py --dry-run --dolibarrDir=/var/www/dolibarr/htdocs

El interruptor -X utf8 es necesario si el juego de caracteres predeterminado no es Unicode (lo cual ocurre con mayor frecuencia).

$ py -X utf8 docDBmigrateScripts.py --dry-run --dolibarrDir=\Apache24\htdocs\dolibarr

Estás solicitando la ejecución de docDBmigrateScripts.py, con el interruptor --dry-run, indicando la ubicación de Dolibarr /var/www/dolibarr/htdocs (o \Apache24\htdocs\dolibarr). El programa verifica que encuentra Dolibarr en esa ubicación, que existe la carpeta de documentos y que la configuración de los archivos fuente es correcta. Luego, solicita una confirmación:

$ 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

Se solicita una confirmación (ingresa y). De todos modos, como indicaste --dry-run, no se realizarán cambios.
¡Ten en cuenta! Si has modificado algunos archivos fuente de Dolibarr (la ubicación se indica en el paso --checking source files referenced), o si la versión de los archivos es diferente a la esperada, esto no funcionará y el programa no avanzará. Mostrará algo como:

some source file(s) referenced in ./scriptFiles/16.0.5 are not OK
nothing was done, see you later

Si has confirmado, el programa muestra:

-- 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)

Muestra una lista de los numerosos scripts a modificar, así como las funciones PHP que se modificarán entre corchetes. En el siguiente ejemplo, se anticipa la modificación de las funciones 'is_dir', 'opendir', 'readdir' en el script migrate_picture_path.php.
Ten en cuenta la frase migration should not act as expected. Significa que la cantidad de scripts no coincide con la esperada. Esto ocurre cuando se ha instalado uno o más módulos. El programa solo conoce la cantidad de scripts estándar, por lo que muestra esta diferencia. No es importante, el trabajo se realizará siempre que se elimine --dry-run de nuestro comando. Veamos:

$ python3 docDBmigrateScripts.py --dolibarrDir=/var/www/dolibarr/htdocs

$ py -X utf8 docDBmigrateScripts.py --dolibarrDir=\Apache24\htdocs\dolibarr

En nuestro ejemplo, obtendremos lo siguiente:

migration not done as expected (578 files, 3589 changes; migrated but 574/3558 expected)

La palabra clave importante aquí es migrated, lo cual significa que el trabajo se ha realizado.
En este punto, si consultáramos Dolibarr, tendríamos la impresión de que nuestros documentos han desaparecido. No te preocupes, aún estarían en el mismo lugar, pero como Dolibarr estaría consultando la base de datos en lugar del sistema de archivos y dicha base de datos no contendría ningún documento, Dolibarr mostraría errores.

> Conversión de documentos

El método para convertir los documentos es similar al que se utiliza para los scripts de PHP. Se ejecuta un comando (docDBmigrateFiles.py en este caso) con verificaciones, confirmación y resultado. Intentemos con --dry-run. Ten en cuenta que se proporciona el directorio de Dolibarr como argumento, no el directorio de los documentos de Dolibarr. Es importante tener acceso al archivo de configuración para conectarse a la base de datos.

$ python3 docDBmigrateFiles.py --dry-run --dolibarrDir=/var/www/dolibarr/htdocs

Si PHP no está en el path, es necesario usar el argumento --phpdir.

$ py -X utf8 docDBmigrateFiles.py --dry-run --dolibarrDir=\Apache24\htdocs\dolibarr --phpdir=\php

El resultado con la solicitud de confirmación:

El programa indica en este caso que hay 15 documentos para migrar. Ten en cuenta que una instalación reciente de Dolibarr no contiene ningún documento (en ese caso, el mensaje sería: 0 documentos en la base de datos).
Confirmemos para verlo.

-- 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 última línea nos indica que todo debería funcionar correctamente. Por supuesto, el uso de --dry-run no es obligatorio en absoluto y podríamos haber ejecutado el comando directamente.

$ python3 docDBmigrateFiles.py --dolibarrDir=/var/www/dolibarr/htdocs

$ py -X utf8 docDBmigrateFiles.py --dolibarrDir=\Apache24\htdocs\dolibarr --phpdir=\php

con el siguiente resultado:

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

En esta ocasión, la migración se ha completado (documents migration done). El programa propone mover el directorio de documentos. Esto te confirmará durante el funcionamiento de Dolibarr que el acceso se realiza correctamente en la base de datos y no en la ubicación habitual donde ya no se encuentran los documentos. Sin embargo, asegúrate de mantener los directorios y archivos indicados en su lugar correcto, de lo contrario, el funcionamiento de Dolibarr se verá gravemente afectado.
Además, se menciona creating directories, ¿de qué se trata si los documentos ahora están en una base de datos? Es simplemente que docDB emula el comportamiento estándar de los archivos y necesita una tabla (llx_doc_directory) que contenga los nombres de los directorios que se supone contienen los documentos. En realidad, los documentos se encuentran en otra tabla (llx_doc_data) que actúa como un contenedor. Puedes conectarte a MySQL y ejecutar las consultas para ver de qué se trata:

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

Por supuesto, las partes útiles de los documentos no se muestran aquí.
Además, si Dolibarr acaba de ser instalado, obtendrá después de cada una de las dos consultas: Empty set o Table doesn't exist.
Para obtener más explicaciones sobre el funcionamiento de estas tablas, visite el wiki de Dolibarr.

> Ping

Por favor, dime que has instalado docDB. Eso me dará una idea de cuántas personas están interesadas en este módulo.

$ python3 docDBping.py

$ py -X docDBping.py

> Reinicio del servidor web

Un simple comando:

# systemctl start apache2

> net start Apache2.4

Listo, eso es todo.
No olvide ajustar su procedimiento de copias de seguridad. Simplemente elimine la parte relacionada con el directorio que contenía los documentos. En cuanto a la base de datos, no hay cambios, excepto que la copia de seguridad será más voluminosa y llevará más tiempo.
Un último comentario: el esfuerzo necesario para cambiar a Linux no es tan grande y el retorno de la inversión es tan rápido.

Volver al estado estándar (desinstalación)

Supongamos que después de un período de prueba, la solución docDB no le conviene. Digamos que ha cambiado de opinión y le gustaría volver al estado estándar. Por cierto, me gustaría saber por qué, no dude en decírmelo :-)
Esto es posible, solo necesita repetir exactamente el mismo procedimiento, pero agregando --reverse a los comandos docDBmigrateScripts.py y docDBmigrateFiles.py. Esto le sería útil si los usuarios de Dolibarr han agregado datos, en cuyo caso las copias de seguridad que haya realizado antes de la migración no estarán actualizadas.

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

Por supuesto, también se puede usar --dry-run en esta operación.
Debe detener el servidor web antes de la operación y es posible que deba modificar los permisos de acceso a los documentos después de la operación (es probable que el usuario con el que está realizando la operación no dé acceso al usuario de Apache). Los comandos necesarios se le mostrarán al final de la operación. Y no olvide eliminar las tablas llx_doc_directory y llx_doc_data de la base de datos después de la operación.

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 caso de actualización de Dolibarr

¿Qué sucede en este caso? Bueno, es muy sencillo: debe actualizar sus scripts de Dolibarr como de costumbre en la carpeta del servidor web y antes de poner en funcionamiento (es decir, antes de iniciar la actualización dentro de Dolibarr), ejecute nuevamente el comando docDBmigrateScripts.py. De lo contrario, Dolibarr no encontrará sus documentos. Se debe tener en cuenta que docDBmigrateScripts.py se puede ejecutar varias veces sin problemas. Si no encuentra ningún script PHP para migrar, simplemente no hará nada. Esto es lo que sucede si se ejecuta dos veces seguidas.
Sin embargo, hay una diferencia: algunos scripts específicos (los que se encuentran en la carpeta install/scriptFiles) se copiarán automáticamente. Son aquellos cuya migración automática era demasiado arriesgada de programar. No hay ningún impacto si no han cambiado en la nueva versión de Dolibarr. De lo contrario, es mejor esperar a la versión de DocDB que tenga en cuenta esta nueva versión de Dolibarr.
Por otro lado, se debe tener precaución al usar docDBmigrateFiles.py porque sobrescribe el contenido de los documentos en la base de datos. Si los usuarios han cargado o generado documentos, es posible que se pierdan. El uso de este comando es completamente innecesario y casi seguro que será perjudicial una vez que haya comenzado a utilizar Dolibarr con docDB.

Si agrega un módulo a Dolibarr

Si su módulo está instalado en Dolibarr antes de la instalación de DocDB, no necesita hacer nada especial. El programa de conversión se encargará de los scripts adicionales y convertirá las funciones relacionadas con los documentos.
Si instala su módulo después, proceda como de costumbre pero vuelva a ejecutar el programa de conversión, primero en modo de prueba. Le indicará los scripts no convertidos y los convertirá si lo confirma.
Si su módulo no maneja documentos de manera especial, no se verá afectado. En caso contrario, pruébelo cuidadosamente antes de ponerlo en producción.