Paperless-ngx

Paperless-ngx convierte documentos en un archivo digital consultable. Importa ficheros, extrae texto, ejecuta OCR, clasifica metadatos y conserva el original junto con su versión procesada.

Qué despliega

paperless: aplicación principal y consumidor de documentos.
paperless-db: PostgreSQL para metadatos.
paperless-redis: cola y caché.
paperless-tika: extracción de texto de formatos Office y similares.
paperless-gotenberg: conversión de documentos a PDF.
paperless-ai: clasificación y enriquecimiento asistido por un LLM.
paperless-inbox-sync: copia periódica desde una carpeta WebDAV de Nextcloud hacia consume.

Los servicios de datos viven en paperless_internal. Paperless y Paperless AI también se unen a proxy para ser alcanzables por Traefik y por servicios compartidos como LiteLLM.

Configuración principal

El .env local agrupa:

Grupo	Variables principales	Por qué existe
PostgreSQL	`PAPERLESS_DBNAME`, `PAPERLESS_DBUSER`, `PAPERLESS_DBPASS`	Conserva índices, usuarios y metadatos
URL y seguridad	`PAPERLESS_DOMAIN`, `PAPERLESS_SECRET_KEY`, `PAPERLESS_ALLOWED_HOSTS`, `TRUSTED_PROXIES`	Genera enlaces correctos y valida peticiones tras Traefik
Administrador	`PAPERLESS_ADMIN_USER`, `PAPERLESS_ADMIN_PASSWORD`, `PAPERLESS_ADMIN_MAIL`	Crea el usuario inicial; cambia la contraseña tras el alta
Correo	variables `PAPERLESS_EMAIL_*`	Notificaciones mediante `mail_internal`
Nextcloud	`NC_DOMAIN`, `NC_WEBDAV_USER`, `NC_WEBDAV_PASS`	Lee la bandeja de entrada remota
Sincronización	`RCLONE_SYNC_INTERVAL`, `PAPERLESS_INBOX_DIR`	Controla frecuencia y carpeta origen

PAPERLESS_CONSUMER_POLLING hace la importación más fiable cuando los archivos llegan por sincronización o montaje y no generan eventos inotify normales.

Persistencia

Ruta	Contenido
`/opt/paperless/pgdata`	PostgreSQL
`/opt/paperless/data`	Índices y estado de Paperless
`/opt/paperless/media`	Originales y documentos procesados
`/opt/paperless/export`	Exportaciones
`/opt/paperless/consume`	Bandeja de importación
`/opt/paperless-ai/data`	Configuración y estado de Paperless AI
`/opt/rclone`	Configuración auxiliar de rclone

La copia de seguridad debe mantener coherencia entre PostgreSQL, data y media. Respaldar sólo la base de datos no conserva los documentos.

Integración de Paperless AI con LiteLLM y Codex

Paperless AI no se conecta directamente a Codex. Se configura como cliente compatible con OpenAI y llama a LiteLLM:

API provider: OpenAI compatible
Base URL: http://litellm:4000/v1
API key: valor de LITELLM_MASTER_KEY
Model: gpt-5.6-sol

Ambos contenedores comparten la red externa proxy, por lo que litellm se resuelve por DNS interno. La configuración de Paperless AI se guarda en /opt/paperless-ai/data; actualmente no se declara mediante variables en el Compose y debe introducirse desde su interfaz.

Flujo de una clasificación:

Paperless -> Paperless AI -> LiteLLM -> proveedor Codex -> Codex

Esta arquitectura es intencionada:

auth.json y el refresh token de Codex permanecen sólo en LiteLLM.
Paperless AI recibe una clave de LiteLLM revocable, no la sesión de Codex.
El alias de modelo puede cambiar de proveedor sin reconfigurar Paperless AI.
LiteLLM centraliza control, logs y futuros límites de consumo.

No montes /home/felidae/.codex/auth.json en Paperless AI. Tampoco uses el dominio público de LiteLLM desde Docker salvo que necesites atravesar Traefik; la URL interna evita una vuelta innecesaria por DNS público y TLS.

Antes de activar clasificación automática, prueba con pocos documentos y revisa qué contenido se envía al modelo. Los documentos pueden contener datos personales o confidenciales.

Sincronización desde Nextcloud

paperless-inbox-sync usa WebDAV y el script /opt/paperless/rclone-sync.sh para copiar la carpeta configurada hacia /consume. Es un flujo unidireccional; comprueba el comportamiento exacto del script antes de cambiarlo por una sincronización con borrado.

La contraseña WebDAV debe ser una contraseña de aplicación dedicada, con el mínimo acceso necesario. No uses la contraseña principal del usuario de Nextcloud.

Despliegue

cd paperless
docker compose --env-file .env config
docker compose --env-file .env up -d

Verificación y operación

docker compose --env-file .env ps
docker compose --env-file .env logs -f paperless
docker compose --env-file .env logs -f paperless-ai
docker compose --env-file .env logs -f paperless-inbox-sync

Comprueba que PostgreSQL, Redis, Tika y Gotenberg estén sanos antes de diagnosticar la aplicación. Si no entran documentos, revisa primero el sync, después /opt/paperless/consume y finalmente los logs del consumidor.