Instalación del gestor documental Paperless-NGX usando Docker compose

En el mercado existe una gran variedad de gestores documentales, pero la mayoría son tremendamente caros y muchos de ellos requieren además estar alojados en servidores ajenos.

Uy, sí. Recuerdo que no hace mucho miramos de implementar en mi empresa Docuware, que tiene una pinta estupenda. Pero si queríamos instalarlo localmente en nuestros servidores el importe era prohibitivo. Si lo que queríamos era usarlo en servidores ajenos era más barato pero con un coste mes a mes por usuario elevado (aunque más barato a priori), pero siempre dependiendo de servidores ajenos, así que si dejábamos de pagar, adiós a todo lo que habíamos organizado. 

Efectivamente Usuario Anónimo. Docuware (de Ricoh), es uno de los mejores gestores documentales que he tenido la oportunidad de revisar e incluso en mi empresa lo estuvimos valorando muy seriamente. No puedo decir más que cosas buenas de la calidad de este gestor documental. Pero el gran problema de este software son los costes. El licenciamiento es enormemente caro para empresas pequeñas, e incluso una empresa mediana tiene que analizar con calma si le compensa tal desembolso.

Pero por desgracia no es el único gestor documental que adolece de este problema. Therefore de Canon también es una excelente alternativa, pero tiene unos precios muy similares, con lo que deja de ser accesible para empresas pequeñas. Al final resulta complicado encontrar un gestor documental de calidad que tenga además unos costes asumibles para una PYME, y aún menos para un usuario particular.

¿Cómo que para un usuario doméstico? Nadie en sus cabales se gastaría una fortuna para tener un gestor documental en su casa. 

Olvídate de precios. Si tuvieras la oportunidad de tenerlo sin costes ¿A que no estaría nada mal disfrutar de un gestor documental propio en casa? Y por supuesto ¿A que también estaría bien disponer de uno en nuestra pequeña empresa a coste cero?

A ver, tío: Tú es que lo quieres todo. Evidentemente si el software es bueno tiene que tener un precio. Los programadores tienen que comer, tienen vicios oscuros que deben pagar e incluso a veces tienen familia y mascotas que mantener y... Bueno... pareja e hijos no creo, que al fin y al cabo son informáticos y se pasan la vida pegados a la pantalla, pero...

¡Para, para! Estás pensando fuera del recipiente. Veo que te estás olvidando que la comunidad de software libre está creando continuamente software de calidad, y que además gran parte de ese software es gratuíto. Dado que con todos los tutoriales previos que hemos hecho ya somos unos auténticos expertos en instalar aplicaciones mediante Docker, una opción muy potente e interesante es usar Docker Compose para realizar una instalación de Paperless-ngx en un pequeño servidor.

Paperless-ngx es un software de código abierto enfocado a la gestión y organización de documentos digitales. Permite a los usuarios escanear, almacenar, buscar y etiquetar documentos de forma sencilla y eficiente, eliminando la necesidad de guardar toda esa documentación en papel y facilitando la administración de documentos en formato digital. Tiene un sistema que lee el contenido de los documentos que vas subiendo (OCR) e indexa todo aquello que ha leído. Además puedes etiquetar los documentos que vas subiendo, de forma que hacer búsquedas a posteriori (tanto por contenido como por etiquetas) resulta muy sencillo.

¡Ostras Pedrín! Entonces ¿Existe un gestor documental potente completamente libre? Primera noticia que tengo. Oye, por cierto, ahora que hablas de Docker. ¿Tú no estabas haciendo tutoriales de cómo instalar cosas con docker en Raspberrys? ¿Esto lo puedo instalar en la mía?

Efectivamente. Podemos realizar la instalación de Paperless-ngx sin ningún tipo de problema en una Raspberry siguiendo las instrucciones que vamos a dar en este artículo (siempre que tenga más de 2 GB de RAM). Aunque voy a matizar lo que te acabo de decir: sin ningún tipo de problema más allá del rendimiento y del consumo de recursos que supone esta instalación.

Entonces ¿Por qué este no es el artículo número 20 de esa serie de artículos? 

Tengo mis motivos. Deja que te explique: este docker, completamente vacío, instalado en mi raspberry me ocupa 1 GB de ram. Además, a pesar de que una vez instalado funciona correctamente y sin problemas, la instalación sobre una raspberry es bastante más lenta que los dockers que hemos visto hasta ahora.

Es por ese motivo por el que no voy a incluir este artículo entre los tutoriales de Raspberry. Podemos instalarlo sin problema en una (de hecho mientras elaboro el tutorial voy a ir instalándolo en una Raspberry Pi 4 para no olvidarme de ningún paso), pero estoy en la obligación de advertiros: por un lado el consumo de recursos en una Raspberry es elevado, así que valorad vosotros mismos si queréis instalarlo en la vuestra. Por otro lado no creo que haya demasiados usuarios domésticos interesados en esta instalación, así que por eso voy a separar este artículo del resto y lo voy a enfocar hacia instalaciones empresariales.

En todo caso, si tenéis dudas yo os diría que hagáis la prueba y lo instaléis en vuestra raspberry. Las instrucciones para realizar una instalación de Paperless-ngx en Raspberry son las mismas que para instalarlo en un PC o servidor X64, así que este tutorial os servirá perfectamente. En el peor de los casos, si no os convence, elimináis el contenedor de la raspberry y aquí no ha pasado nada (ya sabéis que eliminar contenedores es muy sencillo y no dejan rastro ni consecuencias en otras instalaciones).

A ver... para centrarme. ¿Entonces crees que es mejor este sistema de gestión documental que cualquier otro de pago?

No estoy diciendo eso. Lo que te digo es que muchas veces nos tiramos hacia el software propietario y de pago cuando realmente hay soluciones libres grautítas que nos sirven para lo que queremos. No voy a discutir que haya mejores gestores documentales, pero este es muy potente (posiblemente mucho más de lo que te puedas imaginar ahora mismo). Cuando subes un archivo PDF escaneado te hace un OCR del contenido y luego te permite efectuar búsquedas entre todos los documentos subidos por el contenido de los mismos, además de poder etiquetar cada documento y hacer mil cosas a mayores. Además es libre, no le estamos dando nuestros documentos a servidores ajenos y, oye…

Si para lo que queremos hacer nos sirve, pues genial. Y si no, pues a lo mejor sí que hay que plantearse mirar otras opciones.

Pongámonos la ropa de faena y vamos a remangarnos, que a pesar de ser sencilla, esta instalación tiene bastante chicha.

0) Requisitos previos.

Para esta instalación vamos a necesitar lo siguiente:

• Un equipo con una distribución Linux instalada (orientada a ser usada como servidor, como un Ubuntu Server, Debian, o Raspberry Pi OS). Nos sirve que el equipo sea X64 o ARM, pero no nos servirán equipos x86 (necesitamos un equipo de 64 bits).
• Que el equipo tenga instalado Docker y Docker compose para desplegar nuestro nuevo contenedor. Hemos dejado un tutorial de instalación de Docker en este artículo.
• Voy a suponer que sabéis cómo hacer una instalación de un contenedor de Docker, pero si tenéis alguna duda, en este artículo abordamos muy detalladamente la instalación de uno muy sencillito. A lo mejor os puede ser útil para saber cómo proceder con este tipo de instalaciones.
• También voy a suponer que ya tenéis un proxy montado, al menos como el que hemos montado en este artículo (pero sirve cualquier otro tipo de proxy).

1) Creamos la estructura de carpetas de Paperless-ngx.

En todos los artículos que hemos dedicado a instalar contenedores de Docker, siempre hemos sido muy ordenados, así que hemos optado por organizar nuestras carpetas de una forma casi paranoica. En este artículo no vamos a ser menos, así que en la carpeta «home» de nuestro usuario de linux, vamos a crear una carpeta llamada «docker» (en el caso de que no la tengamos ya creada) y nos metemos dentro de ella con los siguientes comandos.

mkdir docker
cd docker

Una vez dentro de esa carpeta vamos a crear un directorio específico para la instalación de Paperless-ngx y dentro de él crearemos todas las carpetas que va a necesitar esta instalación. Lo haremos con los siguientes comandos.

mkdir paperless
cd paperless
mkdir consume && mkdir data && mkdir dbdata && mkdir export && mkdir media && mkdir redisdata

¡Virgencita del tanga de leopardo! ¡6 Carpetas! Hasta ahora no habíamos desplegado ningún docker que necesitase tantas carpetas. 

Sí. Es que este Docker va a crearnos cinco servicios diferentes, cada uno en un contenedor separado. Así que al final vamos a necesitar un montón de carpetas para que esos servicios funcionen correctamente. No te preocupes por ello. Ahora vamos a crear el archivo de configuración de nuestro docker.

2) Creamos el archivo de configuración para nuestra instalación de Paperless-ngx

Dentro de la carpeta paperless vamos a crear el archivo de configuración de Docker Compose que nos permitirá desplegar este programa. Para ello primero tecleamos este comando en el terminal…

sudo nano docker-compose.yml

… y luego le pegamos exactamente este contenido dentro (No modifiquéis nada de lo que haya aquí dentro).

# - Run 'docker compose pull'.
# - Run 'docker compose run --rm webserver createsuperuser' to create a user.
# - Run 'docker compose up -d'.
services:
  broker:
    image: docker.io/library/redis:7
    restart: unless-stopped
    volumes:
      - $DOCKERDIR/paperless/redisdata:/data

  db:
    image: docker.io/library/mariadb:11
    restart: unless-stopped
    volumes:
      - $DOCKERDIR/paperless/dbdata:/var/lib/mysql
    environment:
      MARIADB_HOST: paperless
      MARIADB_DATABASE: $MARIADB_DATABASE
      MARIADB_USER: $MARIADB_USER
      MARIADB_PASSWORD: $MARIADB_PASSWORD
      MARIADB_ROOT_PASSWORD: $MARIADB_ROOT_PASSWORD

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
      - gotenberg
      - tika
    ports:
      - "8004:8000"
    volumes:
      - $DOCKERDIR/paperless/data:/usr/src/paperless/data
      - $DOCKERDIR/paperless/media:/usr/src/paperless/media
      - $DOCKERDIR/paperless/export:/usr/src/paperless/export
      - $DOCKERDIR/paperless/consume:/usr/src/paperless/consume
    env_file: .env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBENGINE: mariadb
      PAPERLESS_DBHOST: db
      PAPERLESS_DBUSER: $MARIADB_USER # only needed if non-default username
      PAPERLESS_DBPASS: $MARIADB_PASSWORD # only needed if non-default password
      PAPERLESS_DBPORT: 3306
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998

  gotenberg:
    image: docker.io/gotenberg/gotenberg:8.7
    restart: unless-stopped
    # The gotenberg chromium route is used to convert .eml files. We do not
    # want to allow external content like tracking pixels or even javascript.
    command:
      - "gotenberg"
      - "--chromium-disable-javascript=true"
      - "--chromium-allow-list=file:///tmp/.*"

  tika:
    image: docker.io/apache/tika:latest
    restart: unless-stopped

volumes:
  data:
  media:
  dbdata:
  redisdata:

Me estoy asustando. Ese código es muy largo. ¿Seguro que la instalación de Paperless-ngx es sencilla?

Tan sencilla como cualquiera de las instalaciones que hemos hecho hasta ahora en los anteriores tutoriales. No te asustes, que por el momento vamos por el buen camino. Simplemente guarda los cambios en el archivo con Control + O y sal del editor de texto con Control + X.

3) Creamos el archivo de variables de entorno.

Supongo que os estáis imaginando que si el docker-compose.yml es tan largo, el archivo de variables de entorno debe ser también extenso. Pues no os equivocáis. Dentro de la carpeta paperless vamos a crear el archivo con el siguiente comando:

sudo nano .env

Una vez dentro del editor Nano, vamos a pegar este código (Ojo, que esto sí que lo vamos a modificar).

DOCKERDIR=/home/<tu_usuario>/docker
COMPOSE_PROJECT_NAME=paperless
##
USERMAP_UID=1000
USERMAP_GID=1000
PAPERLESS_URL=https://docs.dominio.es
PAPERLESS_SECRET_KEY=ponalgocomoestorGaregaretrAEgrgardGsret34Faergsreg5s4wafa
PAPERLESS_TIME_ZONE=Europe/Madrid
PAPERLESS_OCR_LANGUAGE=spa
##
MARIADB_DATABASE=paperless
MARIADB_USER=elusuariodepl
MARIADB_PASSWORD=laclavedeLpsmasLoca
MARIADB_ROOT_PASSWORD=lavesloquisimaR3stgtrst

La parte de la derecha de casi todas estas variables debemos cambiarla. Os explico qué vamos a poner en cada línea.

• DOCKERDIR: Aquí debe ir la ruta hacia la carpeta docker. Normalmente con modificar la zona que pone <tu_usuario> por el usuario del ordenador host ya debería llegar.
• COMPOSE_PROJECT_NAME: Es el nombre del proyecto. Os recomiendo dejarlo en «paperless».
• USERMAP_UID y USERMAP_GID: Estas líneas tiene que ver con la configuración de los permisos de usuario y grupo en los volúmenes que van a usar los contenedores. Salvo que vuestra instalación sea extraña no os liéis. Dejad ambos valores en 1000.
• PAPERLESS_URL: Poned la dirección web sobre la que váis a montar el gestor documental.
• PAPERLESS_SECRET_KEY: Aquí inventaos una clave absurdamente larga. No os preocupéis por la longitud. No tendréis que ponerla nunca. Eso sí: ¡Ni se os ocurra reutilizar la que os pongo como ejemplo! Usar claves que habéis visto en cualquier web es un riesgo de seguridad.
• PAPERLESS_TIME_ZONE: Poned la zona horaria en la que residís. Por ejemplo, en la España peninsular, podéis poner «Europe/Madrid«
• PAPERLESS_OCR_LANGUAGE: Aquí hay que poner un código de tres letras con el lenguaje (o los lenguajes) en los que el OCR debe reconocer los textos que le vamos a subir. En caso de subir textos en español pondremos «spa«. Si necesitamos varios lenguajes los separaremos con un espacio de esta forma: «spa ita«
• MARIADB_DATABASE: Es el nombre de la base de datos. Podríamos dejarlo en «paperless«
• MARIADB_USER: Es el usuario de la base de datos. Sed creativos y poned algo raro (salvo desastre, no tendréis que usarlo nunca).
• MARIADB_PASSWORD: Es la contraseña del usuario de la base de datos. Poned una larga, extraña y muy dura de recordar (Usuario Anónimo, no hagas chistes).

¡Eh! A mi no me mires, que para una vez que no digo nada...

• MARIADB_ROOT_PASSWORD: De nuevo poned una contraseña extraña aporreando el teclado. Estas dos últimas contraseñas se usarán internamente pero nosotros no necesitaremos usarlas para nada.

Con todo esto ya definido, guardad cambios al archivo con Control + O y salid del editor nano con Control + X.

Ahora vamos a proteger este archivo de variables para que si hay alguna brecha de seguridad no se pueda acceder a él. Simplemente teclead el siguiente comando.

sudo chmod 600 .env

Con esto, ya estamos listos para comenzar la instalación de Paperless-ngx propiamente dicha.

4) Desplegamos la máquina: Instalación de Paperless-ngx

Por fin ya tenemos todo listo. Vamos a desplegar la instalación usando este comando:

sudo docker-compose -p "paperless" up -d

Si habéis hecho más instalaciones de software con Docker Compose, vais a notar dos diferencias: Por un lado, desplegar Paperless-ngx lleva más tiempo (pero mucho más tiempo) que otros Dockers más simples (Como los que hemos visto en los artículos dedicados a las Raspberrys). Da igual que lo despleguéis en una Raspberry o en un ordenador potente: desde el final del despligue hasta que el sitio es accesible pasan varios minutos. Por otro lado, una vez terminado el despliegue, si tecleáis en la consola el comando top, podréis ver que durante unos cuantos minutos en la parte superior de los procesos se sitúa uno de la base de datos, que empieza a consumir bastantes recursos.

¡Ahivá! Pues tiene razón. De hecho tengo la raspberry medio frita. Tarda mucho en hacer cualquier cosa. 

Exacto, pero no te preocupes en exceso. Una vez que se ha instalado todo, el sistema tiene que crear todas las tablas y bases de datos necesarias para su correcto funcionamiento. Este proceso dura en el mejor de los casos unos 2-3 minutos, pero por si acaso dale 5 y así te aseguras de que todo vaya bien. Si quieres puedes ir monitorizando el proceso con el comando top. Cuando el consumo de recursos se haya reducido a algo normal, podemos seguir con la instalación.

¿Cómo que seguir? ¿Pero esto no está ya instalado?

No seas impaciente. Tenemos que crear aún un usuario para poder gestionar el sistema y configurar nuestro proxy. Vamos a ver cómo hacer todo esto.

5) Creamos un usuario para administrar Paperless-ngx.

Esto que vamos a hacer ahora sólo hay que hacerlo una vez (porque una vez creado el usuario «principal», crear otros usuarios es mucho más sencillo). El tema es que en este momento no podemos acceder a nuestra instalación porque no tenemos credenciales para entrar en la web de Paperless-ngx. Así que para crearlas, en cuanto nos hayamos asegurado que el proceso del paso 4 ha terminado correctamente (que ya no está consumiendo una cantidad de recursos ingente), vamos a teclear este comando en el terminal.

sudo docker compose run --rm webserver createsuperuser

Este comando apagará y volverá a encender el docker que acabamos de crear e intentará conectarse con su base de datos (es normal que haga varios intentos de conexión, porque esa base de datos tarda tiempo en levantarse). Luego nos preguntará datos del usuario maestro que estamos creando para nuestra instalación de Paperless-ngx. Por supuesto, los más importantes y que debéis poner con especial cuidado son el nombre de usuario y la contraseña (por favor, no pongáis 1234 de contraseña. Cada vez que lo hacéis, Dios mata a un gatito).

Ah, y no os olvidéis que este docker es grandote. Al terminar, dadle tiempo para que se encienda todo de nuevo, así que sed pacientes.

Vale. Con esto ya podremos entrar en la web que acabamos de crear ¿no? 

Pues no. Como siempre, hay que crear un proxy para poder acceder a nuestra instalación a través de internet. Vamos a ello.

6) Configuración del proxy.

Voy a suponer que tenéis instalado un proxy en vuestras instalaciones (bien dockerizado junto con esto que acabamos de instalar o en otro equipo cualquiera). Para facilitar las cosas, en caso de que no tengáis uno instalado, en este artículo os explico cómo podéis instalar uno de forma sencilla. Voy a suponer que tenéis instalado en algún sitio Nginx Proxy Manager y voy a explicar cómo configurarlo para hacer funcionar nuestra instalación de Paperless-ngx, pero si tenéis algún otro proxy (Virtualmin, traefik o algún otro con apache, por ejemplo) podéis usarlo de la misma forma.

Vamos al lío. En la pantalla principal de Nginx Proxy Manager, debemos pulsar sobre Hosts y luego sobre Proxy Hosts.

Luego pulsaremos el botón que hay arriba a la derecha que pone «Add Proxy Host».

Ahora, en la pantalla que nos sale, debemos cubrir los siguientes campos:

• Forward Port: 8004
• Domain names: ponemos un subdominio del dominio que tenemos contratado. Algo como docs.dominio.es
• scheme: http
• Forward Hostname / IP: ponemos la ip local del host dónde hemos hecho la instalación de Paperless-ngx.

Por último pulsamos Save.

Acordaos siempre que, después de configurar un dominio, hay que habilitar la conexión segura (SSL), porque si no nuestro navegador se va a quejar de la seguridad de la página. Para habilitarlo pulsaremos sobre los tres puntitos que hay al final de la línea del proxy que acabamos de configurar y luego pulsaremos la opción «Edit».

Ahora pulsaremos sobre el desplegable llamado «SSL Certificate» y seleccionamos la opción «Request a new SSL Certificate«. Vamos a marcar también las opciones «Force SSL» y «HTTP/2 Support» . Por último, pulsamos sobre el botón «Save».

7) Login y creación de más usuarios

Con todo esto realizado ya podremos entrar en nuestra instalación usando la dirección web que hemos configurado en el paso 6 y el usuario y contraseña que hemos creado en el paso 5.

OK. Ahora entonces le tengo que dar ese usuario y contraseña a todos lo que quieran usar el gestor documental ¿no?

¡Ni se te ocurra, insensato! ¡Lo que tienes ahora mismo es un usuario administrador! Lo que tienes que hacer es crear un usuario diferente y que no sea administrador a cada una de las personas que tienen que usar el gestor documental. Tienes que ir a la zona de «Usuarios y Grupos» y ahí puedes añadir nuevos usuarios, gestionar sus permisos, e incluso puedes añadir grupos para que cada «departamento» pueda tener su propia organización interna.

Si cacharreáis por la interfaz vais a poder ver que se pueden hacer muchas cosas interesantes, como crear flujos de trabajo, etiquetar documentos y mil cosas más, pero explicar todo ya no es el objetivo de este artículo. Os voy a dejar aquí un vídeo que me parece uno de los mejores en cuanto a introducción a este sistema, para que podáis ver de forma rápida hasta dónde podéis llegar con ésto.

8) Actualización de la instalación de Paperless-ngx

De vez en cuando sería más que conveniente echar un vistazo por si hay alguna actualización que debamos aplicar a nuestro nuevo gestor documental. Para ello creo que lo mejor es hacer un pequeño script que automatice todo. Vamos a ir de nuevo al terminal y vamos a escribir este comando para crearlo:

sudo nano actualizar.sh

Una vez dentro del editor de texto, pegaremos este contenido (acordaos de cambiar en la primera línea lo de «<tu_usuario>» por el usuario de vuestro sistema para que la ruta sea correcta).

cd /home/<tu_usuario>/docker/paperless
sudo docker-compose pull
sudo docker-compose up -d --remove-orphans
sudo docker image prune -f

Después de guardar cambios con Control + O y salir del editor con Control + X, debemos hacer que este script sea ejecutable. Lo haremos con el siguiente comando:

sudo chmod +x actualizar.sh

Ahora, cada vez que queramos comprobar si hay actualizaciones del sistema y aplicarlas, simplemente iremos a la carpeta dónde hemos creado el script y ejecutaremos el siguiente comando.

sudo ./actualizar.sh

Pero puede que éste no sea el único contenedor que tenemos en la carpeta «docker«. Si queremos que se actualicen automáticamente todos los contenedores que hay dentro de esa carpeta, el script sería un poco diferente. Lo haríamos así (De nuevo debemos cambiar la ruta de la línea BASE_DIR="/home/<tu_usuario>/docker" por la ruta correcta:

#!/bin/bash

# Actualizo el sistema operativo
sudo apt-get update -y
sudo apt-get dist-upgrade -y
sudo apt-get autoremove -y
sudo apt-get autoclean -y


# Definimos el directorio base
BASE_DIR="/home/<tu_usuario>/docker"

# Recorro todas las subcarpetas dentro del directorio base
for dir in $BASE_DIR/*; do
  if [ -d "$dir" ]; then
    echo "Procesando $dir ..."
    cd "$dir"
    sudo docker-compose pull
    sudo docker-compose up -d --remove-orphans
    sudo docker image prune -f
  fi
done

# Ya he actualizado todo. Ahora reinicio el sistema. 
sudo shutdown -r now

Con esto ya tendríamos el sistema correctamente montado y listo para ser usado. ¿Qué os parece este gestor documental? ¿Usáis algún otro en vuestro día a día? ¿Os ha dado algún problema el despliegue de Paperless-ngx? Estaré atento a vuestros comentarios.