Paperless-ngx es un gestor documental autoalojado que convierte tus escaneos y PDF en un archivo con búsqueda de texto completo. Cada documento que recibe pasa por OCR, se archiva en PDF/A y se clasifica automáticamente con etiquetas, remitentes y tipos de documento que aprende de tus propias asignaciones. En este tutorial instalarás Paperless-ngx con Docker Compose, PostgreSQL, Tika y Gotenberg en Ubuntu 24.04, configurarás el OCR en español, lo publicarás por HTTPS con Nginx y programarás exportaciones de respaldo.

Requisitos previos

  • Un servidor con Ubuntu 24.04 LTS con al menos 2 núcleos y 4 GB de RAM, por ejemplo un VPS de CubePath. El OCR es intensivo en CPU; más núcleos procesan los documentos más rápido.
  • Un usuario no root con privilegios sudo.
  • Docker Engine y el plugin de Docker Compose instalados desde el repositorio oficial de Docker.
  • Un dominio con un registro A apuntando a la IP del servidor, por ejemplo docs.tu_dominio.

Paso 1: Descargar los ficheros de Compose oficiales

El proyecto mantiene varias variantes de docker-compose.yml en su repositorio. La variante postgres-tika incluye PostgreSQL como base de datos y los servicios Tika y Gotenberg, que permiten procesar también documentos de Office (.docx, .xlsx, .odt) y correos .eml.

mkdir -p ~/paperless-ngx
cd ~/paperless-ngx
wget -O docker-compose.yml https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres-tika.yml
wget -O docker-compose.env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.env
wget -O .env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/.env
  • docker-compose.yml define los servicios: broker (Redis), db (PostgreSQL), webserver (Paperless-ngx), gotenberg y tika.
  • docker-compose.env contiene la configuración de Paperless-ngx.
  • .env fija el nombre del proyecto de Compose (paperless).

Crea las carpetas que el fichero de Compose monta desde el host: consume es la bandeja de entrada de documentos y export es el destino de las copias de seguridad:

mkdir -p ~/paperless-ngx/{consume,export}

Paso 2: Configurar Paperless-ngx

Paperless-ngx necesita una clave secreta para firmar las sesiones. Genérala:

openssl rand -hex 32

Averigua también tu UID y GID, para que los ficheros que Paperless-ngx cree en consume y export pertenezcan a tu usuario:

id -u; id -g

1000
1000

Edita la configuración:

nano ~/paperless-ngx/docker-compose.env

Descomenta (quitando el #) y ajusta estas variables. Deja el resto como está:

USERMAP_UID=1000
USERMAP_GID=1000

PAPERLESS_URL=https://docs.tu_dominio
PAPERLESS_SECRET_KEY=clave_generada_con_openssl
PAPERLESS_TIME_ZONE=Europe/Madrid

# Idiomas del OCR: español e inglés
PAPERLESS_OCR_LANGUAGE=spa+eng

PAPERLESS_URL es obligatorio cuando Paperless-ngx está detrás de un proxy con HTTPS: se usa para la protección CSRF y para los enlaces que genera. La imagen de Docker ya incluye los paquetes de OCR de inglés, alemán, italiano, español y francés; para otros idiomas añade sus códigos de Tesseract a PAPERLESS_OCR_LANGUAGES (en plural), por ejemplo PAPERLESS_OCR_LANGUAGES=por cat.

Protege el fichero:

chmod 600 ~/paperless-ngx/docker-compose.env

Paso 3: Limitar el puerto a localhost

El servicio webserver publica el puerto 8000 en todas las interfaces. Docker gestiona sus propias reglas de iptables, de modo que el puerto quedaría accesible desde internet aunque UFW no lo permita. Nginx será la única entrada, así que publícalo solo en 127.0.0.1:

nano ~/paperless-ngx/docker-compose.yml

En el servicio webserver, cambia ports para que quede así:

    ports:
      - "127.0.0.1:8000:8000"

Paso 4: Arrancar los servicios y crear el administrador

Descarga las imágenes y arranca todo en segundo plano:

cd ~/paperless-ngx
docker compose pull
docker compose up -d

El primer arranque aplica las migraciones de la base de datos y tarda uno o dos minutos. Comprueba el estado:

docker compose ps --format "table {{.Service}}\t{{.Status}}"

SERVICE     STATUS
broker      Up 2 minutes
db          Up 2 minutes
gotenberg   Up 2 minutes
tika        Up 2 minutes
webserver   Up 2 minutes (healthy)

Crea el usuario administrador. El comando te pedirá nombre, correo y contraseña:

docker compose run --rm webserver createsuperuser

Comprueba que la aplicación responde en local:

curl -s -o /dev/null -w "%{http_code}\n" -L http://127.0.0.1:8000/

200

Paso 5: Publicar Paperless-ngx por HTTPS con Nginx

Instala Nginx y Certbot, y abre los puertos web en UFW:

sudo apt install nginx certbot python3-certbot-nginx
sudo ufw allow OpenSSH
sudo ufw allow "Nginx Full"
sudo ufw enable

Crea el sitio:

sudo nano /etc/nginx/sites-available/paperless

server {
    listen 80;
    listen [::]:80;
    server_name docs.tu_dominio;

    # Tamaño máximo de los documentos subidos desde la web
    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket para el estado de procesamiento en tiempo real
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_redirect off;
        proxy_read_timeout 300s;
    }
}

Activa el sitio, valida la configuración y obtén el certificado:

sudo ln -s /etc/nginx/sites-available/paperless /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d docs.tu_dominio

Abre https://docs.tu_dominio e inicia sesión con el administrador. Si ves un error CSRF verification failed, revisa que PAPERLESS_URL coincide exactamente con la URL del navegador y ejecuta docker compose up -d para aplicar el cambio.

Paso 6: Añadir documentos

Hay tres formas habituales de introducir documentos:

  • Desde la web: arrastra PDF o imágenes al panel principal.
  • Carpeta de consumo: cualquier fichero que copies en ~/paperless-ngx/consume se procesa y después se elimina de la carpeta.
  • Correo: Paperless-ngx puede leer una cuenta IMAP y procesar los adjuntos (paso 8).

Prueba la carpeta de consumo con un PDF escaneado:

cp factura-enero.pdf ~/paperless-ngx/consume/

Sigue el procesamiento en el log:

cd ~/paperless-ngx
docker compose logs -f webserver

Cuando termine verás una línea similar a Document factura-enero consumption finished y el fichero desaparecerá de consume. Pulsa Ctrl+C para salir del log. En la web, abre el documento y la pestaña Contenido: debe mostrar el texto extraído por OCR.

Desde tu equipo puedes enviar documentos directamente a la carpeta de consumo por SSH:

scp *.pdf tu_usuario@ip_del_servidor:~/paperless-ngx/consume/

Paso 7: Organizar con etiquetas, remitentes y flujos de trabajo

Paperless-ngx organiza los documentos con tres conceptos:

ConceptoPara qué sirveEjemplos
EtiquetasClasificación libre, varias por documentoImpuestos, Hogar, Coche
RemitentesQuién emite el documentoCompañía eléctrica, Banco, Gestoría
Tipos de documentoQué es el documentoFactura, Contrato, Nómina

Créalos en el menú lateral. Para cada uno puedes elegir un algoritmo de asignación: Auto aprende de los documentos que ya has clasificado a mano, mientras que Cualquier palabra, Todas las palabras, Coincidencia exacta o Expresión regular aplican reglas fijas sobre el texto del documento. Con unas decenas de documentos clasificados, el modo Auto acierta en la mayoría de los casos.

Para acciones más complejas, usa Flujos de trabajo: por ejemplo, un disparador "Documento añadido" con filtro de nombre *nomina* que asigne el tipo Nómina, la etiqueta Trabajo y un propietario concreto.

La búsqueda de texto completo está en la barra superior. Además de palabras sueltas, admite filtros como tag:impuestos, correspondent:banco, type:factura o rangos de fechas como created:[2024 to 2025].

Paso 8: Importar documentos desde el correo

Para que las facturas que recibes por correo lleguen solas, ve a Correo en el menú lateral y añade una cuenta IMAP con el servidor, el puerto (993 con SSL), el usuario y la contraseña. Muchos proveedores, como Gmail, requieren una contraseña de aplicación en lugar de la contraseña normal.

Después crea una Regla de correo para esa cuenta, por ejemplo:

  • Carpeta: INBOX.
  • Filtro de asunto: factura.
  • Acción: procesar los adjuntos y mover el correo a la carpeta Procesados.
  • Asignar la etiqueta Facturas.

Paperless-ngx revisa las cuentas cada 10 minutos. Puedes comprobar el resultado en Registros (sección mail).

Paso 9: Programar copias de seguridad

La herramienta document_exporter vuelca todos los documentos (originales y versiones archivadas) junto con sus metadatos a la carpeta export en un formato que se puede importar en cualquier instalación nueva. Ejecútala a mano para probarla:

cd ~/paperless-ngx
docker compose exec -T webserver document_exporter ../export

Comprueba el resultado:

ls ~/paperless-ngx/export | head

Deberías ver el fichero manifest.json y los documentos exportados. Las siguientes ejecuciones solo copian lo que ha cambiado.

Programa la exportación cada noche con cron:

crontab -e

0 2 * * * cd "$HOME/paperless-ngx" && docker compose exec -T webserver document_exporter ../export > /dev/null 2>&1

Después, copia ~/paperless-ngx/export fuera del servidor con restic, borg o rsync. Para restaurar en una instalación limpia, copia la exportación a export y ejecuta docker compose exec -T webserver document_importer ../export.

Actualizar Paperless-ngx

Haz una exportación (paso 9) y actualiza las imágenes:

cd ~/paperless-ngx
docker compose pull
docker compose up -d

Las migraciones de base de datos se aplican automáticamente al arrancar. Las actualizaciones a una versión mayor de PostgreSQL requieren un volcado y restauración manual; revisa las notas de la versión antes de cambiar la imagen de db.

Solución de problemas

Los documentos se quedan en consume y no se procesan. Revisa docker compose logs webserver --tail 50. Si ves errores de permisos, comprueba que USERMAP_UID y USERMAP_GID coinciden con el propietario de la carpeta (ls -ln ~/paperless-ngx).

El OCR no reconoce bien los acentos o la ñ. Comprueba que el idioma está disponible y configurado:

docker compose exec webserver tesseract --list-langs

La lista debe incluir spa. Si no aparece el idioma que necesitas, añádelo a PAPERLESS_OCR_LANGUAGES y recrea el contenedor. Escanea a 300 ppp para mejores resultados.

Error CSRF verification failed al iniciar sesión. PAPERLESS_URL no coincide con la URL real (esquema, dominio y puerto). Corrígelo en docker-compose.env y ejecuta docker compose up -d.

Los documentos de Office no se procesan. Asegúrate de estar usando la variante postgres-tika y de que los contenedores tika y gotenberg están en marcha con docker compose ps.

Conclusión

Tienes Paperless-ngx funcionando con PostgreSQL, Tika y Gotenberg, publicado por HTTPS con Nginx, con OCR en español, importación desde el correo y exportaciones nocturnas. Como siguientes pasos puedes activar la autenticación en dos pasos en tu perfil, crear usuarios con permisos por documento para compartir el archivo con tu familia o equipo, o usar una app móvil compatible para escanear directamente al servidor.