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

```text
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:

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

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

## Verificación y operación

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