Paperless-ngx en Proxmox LXC: arma un archivo de documentos autoalojado que funciona en 2026

Si tienes una montaña de PDFs, facturas escaneadas, pólizas de seguro y documentos de impuestos en una jerarquía de carpetas aleatoria en tu NAS (o peor, en Google Drive), Paperless-ngx es la solución. Es un sistema de gestión documental open source que recibe los documentos, les aplica OCR y hace que todo el archivo se pueda buscar por texto completo. Lo tengo corriendo en un LXC de Proxmox en mi homelab, y es de esos servicios que volvería a montar de inmediato si mi homelab se quemara.

Esta guía cubre la instalación completa en 2026: contenedor LXC, stack de Docker Compose, almacenamiento con bind mount, integración con escáner y algunos ajustes de nivel producción que la documentación oficial pasa por alto.

¿Qué es Paperless-ngx y por qué autoalojarlo?

Paperless-ngx es un fork de Paperless y Paperless-ng con mantenimiento activo y realmente listo para producción. Dejas un PDF en la carpeta de consumo (desde un escáner de red, el correo o la app móvil) y en pocos minutos tiene OCR, etiquetas, un remitente asignado y se puede buscar por texto completo.

La función estrella es el etiquetado automático asistido: lo vas entrenando con el tiempo y empieza a clasificar documentos solo. Después de unos cientos de documentos, el clasificador es lo bastante preciso como para que rara vez tengas que tocar a mano los documentos nuevos.

Correr Paperless-ngx en tu homelab con Proxmox en lugar de un servicio en la nube significa cero costos por documento, que tus documentos nunca salen de tu red y que tu archivo sobrevive a que cualquier SaaS cierre.

Requisitos previos

Antes de empezar, necesitas:

• Proxmox VE 8.x o 9.x (mira mi guía de actualización a Proxmox VE 9, en inglés, si todavía no actualizaste)
• Al menos 2 vCPU y 2 GB de RAM para el LXC; 4 GB recomendados para un OCR rápido
• Un lugar de almacenamiento para el archivo de documentos (NAS, pool ZFS o un SSD dedicado)
• Opcional pero recomendado: un escáner de documentos en red

Paso 1: ¿cómo creo el contenedor LXC en Proxmox?

Descarga la plantilla LXC de Ubuntu 22.04 si todavía no la tienes:

pveam update
pveam download local ubuntu-22.04-standard_22.04-1_amd64.tar.zst

Crea el contenedor. Con 2 vCPU y 3 GB de RAM vas bien: el OCR exige mucha CPU cuando procesa por primera vez una pila de documentos atrasados:

pct create 110 local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst \
  --hostname paperless \
  --memory 3072 \
  --cores 2 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp \
  --storage local-lvm \
  --rootfs local-lvm:8 \
  --unprivileged 1 \
  --features nesting=1

El flag nesting=1 es necesario para que Docker funcione dentro de un contenedor LXC sin privilegios. Inícialo y obtén la IP:

pct start 110
pct exec 110 -- ip addr show eth0 | grep "inet "

Asigna una IP fija desde tu router o con una reserva DHCP en OPNsense. Elige algo fácil de recordar; 192.168.x.110 funciona bien.

Paso 2: instala Docker dentro del LXC

pct exec 110 -- bash -c "apt-get update && apt-get install -y ca-certificates curl gnupg"
pct exec 110 -- bash -c "install -m 0755 -d /etc/apt/keyrings && \
  curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg && \
  chmod a+r /etc/apt/keyrings/docker.gpg"
pct exec 110 -- bash -c 'echo \
  "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" > /etc/apt/sources.list.d/docker.list'
pct exec 110 -- bash -c "apt-get update && apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin"

Verifica que funcione:

pct exec 110 -- docker run --rm hello-world

Paso 3: ¿cómo configuro el almacenamiento del archivo de documentos?

No guardes tu archivo de documentos dentro del rootfs del LXC: ponlo en un volumen de almacenamiento como corresponde. Un dataset ZFS en el nodo principal de Proxmox es una buena opción.

En el host de Proxmox, crea el dataset y las carpetas:

zfs create rpool/paperless
mkdir -p /rpool/paperless/{data,media,export,consume}
chown -R 1000:1000 /rpool/paperless

Móntalas en el LXC agregando esto a /etc/pve/lxc/110.conf:

mp0: /rpool/paperless,mp=/paperless

Reinicia el contenedor:

pct restart 110

Dentro del LXC, verifica el montaje:

pct exec 110 -- ls /paperless
# should show: consume  data  export  media

Si vas a guardar los documentos en un disco de NAS en lugar de un pool ZFS local, el Seagate IronWolf de 4 TB y el WD Red Plus de 4 TB están pensados para cargas de NAS y son mucho más confiables que los discos de escritorio bajo escritura continua. Si buscas algo más económico, un SSD Samsung 870 EVO de 2 TB como disco del archivo te da una excelente velocidad de lectura aleatoria al buscar.

Paso 4: configura el stack de Docker Compose

Dentro del LXC, crea /opt/paperless/docker-compose.yml:

mkdir -p /opt/paperless
cat > /opt/paperless/docker-compose.yml << 'EOF'
version: "3.4"

services:
  broker:
    image: docker.io/library/redis:7
    restart: unless-stopped
    volumes:
      - redisdata:/data

  db:
    image: docker.io/library/postgres:16
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: changeme_strong_password

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - "8000:8000"
    volumes:
      - /paperless/data:/usr/src/paperless/data
      - /paperless/media:/usr/src/paperless/media
      - /paperless/export:/usr/src/paperless/export
      - /paperless/consume:/usr/src/paperless/consume
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: changeme_strong_password
      PAPERLESS_OCR_LANGUAGE: eng
      PAPERLESS_SECRET_KEY: changeme_generate_with_openssl_rand_-hex_32
      PAPERLESS_TIME_ZONE: America/New_York
      PAPERLESS_URL: http://192.168.1.110:8000
      PAPERLESS_OCR_THREADS: 2
      PAPERLESS_CONSUMER_POLLING: 60
      PAPERLESS_TASK_WORKERS: 2
      PAPERLESS_THREADS_PER_WORKER: 1

volumes:
  pgdata:
  redisdata:
EOF

Ajusta PAPERLESS_OCR_LANGUAGE según tus documentos: usa eng+spa para inglés + español.

Genera una clave secreta real:

pct exec 110 -- bash -c "docker run --rm -it ghcr.io/paperless-ngx/paperless-ngx:latest python3 -c 'import secrets; print(secrets.token_hex(32))'"

Levanta el stack:

pct exec 110 -- bash -c "cd /opt/paperless && docker compose up -d"

Crea el usuario administrador:

pct exec 110 -- bash -c "cd /opt/paperless && docker compose exec webserver python3 manage.py createsuperuser"

Entra a http://192.168.1.110:8000 en tu navegador y deberías ver la interfaz de Paperless-ngx.

Paso 5: ¿cómo integro un escáner?

Escáneres de red

Si tienes un escáner con red, apúntalo directamente a la carpeta de consumo o exponla por Samba:

pct exec 110 -- bash -c "apt-get install -y samba"
cat >> /etc/samba/smb.conf << 'EOF'

[paperless-consume]
   path = /paperless/consume
   browseable = yes
   read only = no
   guest ok = no
   valid users = paperless
EOF
pct exec 110 -- bash -c "smbpasswd -a paperless && systemctl restart smbd"

En cuanto a escáneres, el Fujitsu ScanSnap iX1600 es el estándar de oro para escanear documentos en una oficina en casa: dúplex, 40 ppm y su app puede enviar directamente a una carpeta por WiFi. El Canon imageFORMULA R40 es una buena opción de gama media si no quieres gastar más de $400. Para un uso más ligero, el Epson WorkForce ES-400 II maneja sin problemas el volumen típico de una oficina en casa.

Escaneo desde el móvil

Instala la app móvil oficial de Paperless-ngx (iOS/Android) o Paperless Mobile. Apúntala a la URL de tu Paperless-ngx con tus credenciales: puedes tomarle una foto a un recibo y tenerlo procesado y etiquetado en menos de dos minutos.

Para acceso remoto sin abrir puertos, poner Cloudflare Tunnels delante de Paperless-ngx es lo más limpio: cero puertos expuestos y el plan gratis maneja el tráfico sin problema.

Paso 6: ¿cómo funciona el entrenamiento de la clasificación automática?

El clasificador de Paperless-ngx necesita documentos para entrenar. Ve a Admin → Machine Learning → Run trainer cuando tengas más de 50 documentos cargados. Después de unos 200 documentos con remitentes y etiquetas bien asignados, la asignación automática se vuelve realmente útil.

La taxonomía de etiquetas importa. Mantenla plana y amplia en lugar de profunda y específica: tax, insurance, medical, utilities, bank, receipts. Las jerarquías profundas confunden al clasificador.

Paso 7: agrega HTTPS con Traefik

No corras Paperless-ngx sobre HTTP en producción, ni siquiera en tu red local. Si ya usas Traefik en Proxmox LXC, agrega enrutamiento por etiquetas al archivo compose:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.paperless.rule=Host(`paperless.yourdomain.internal`)"
  - "traefik.http.routers.paperless.tls=true"
  - "traefik.http.routers.paperless.tls.certresolver=letsencrypt"
  - "traefik.http.services.paperless.loadbalancer.server.port=8000"

Actualiza PAPERLESS_URL en tu archivo compose con el hostname HTTPS y reinicia.

Estrategia de respaldos

Tu archivo de documentos es irremplazable. Paperless-ngx trae un comando de exportación integrado:

docker compose exec webserver document_exporter /paperless/export

Agrégalo a un cron dentro del LXC y sincroniza la carpeta de exportación a un SSD externo o a un bucket S3 fuera de casa con rclone. Una buena rutina es exportar cada noche y sincronizar a un Samsung T7 Shield de 2 TB conectado a otra máquina.

Para la carpeta de medios (los archivos de los documentos), usa Proxmox Backup Server o replicación de snapshots de ZFS. La carpeta de medios más un volcado de PostgreSQL es tu set completo de recuperación:

docker compose exec db pg_dump -U paperless paperless > /paperless/export/paperless-db-$(date +%Y%m%d).sql

¿Qué hardware necesita Paperless-ngx?

En reposo, el stack de Paperless-ngx usa aproximadamente 180 MB de RAM. Durante la ingesta masiva con OCR de un PDF de varias páginas sube a 600-800 MB y satura un núcleo de CPU. Con 3 GB asignados y PAPERLESS_OCR_THREADS: 2, los lotes grandes terminan sin quedarse sin memoria.

Cualquier equipo que corra Proxmox con soltura maneja Paperless-ngx como un LXC más entre muchos. Un Beelink GTi13 Ultra, un Intel NUC 12 Pro usado o un Dell OptiPlex 7090 reacondicionado tienen margen de sobra para correr Paperless junto a Immich, Jellyfin y otros servicios.

Si quieres correr todo el stack más la clasificación automática sin que nada se frene, agrega un segundo NVMe para el pool ZFS: el WD Black SN850X de 2 TB es una buena opción por su E/S aleatoria rápida en la carpeta de medios.

Advertencias y detalles

Los paquetes de idioma de OCR pesan. Cada idioma adicional de Tesseract suma ~30-100 MB a la imagen del contenedor. Instala solo los que necesitas.

Conversión a PDF/A. Por defecto, Paperless-ngx convierte los documentos a PDF/A para archivarlos a largo plazo. Es el comportamiento correcto, pero puede cambiar bastante el tamaño de los archivos: una factura escaneada de 2 MB puede convertirse en un PDF/A de 4 MB. Planifica el almacenamiento en consecuencia.

Reindexar la búsqueda toma tiempo. Después de actualizar de versión, Paperless a menudo necesita reconstruir el índice de búsqueda de texto completo. En un archivo grande (más de 5.000 documentos), esto puede tardar 20-30 minutos. No reinicies el contenedor a mitad del proceso.

Detalle de red en LXC. Si el contenedor del servidor web no puede resolver broker o db por hostname, puede que la red de Docker dentro del LXC sin privilegios tenga un problema de DNS. Agregar --dns 1.1.1.1 a la configuración de red del compose suele resolverlo.

Consejo para cargar documentos atrasados. Si vas a cargar más de 1.000 documentos atrasados, hazlo de a 100. Soltar mil PDFs de golpe genera una cola de tareas que puede hacer que Redis consuma memoria de forma inesperada.

Veredicto

Paperless-ngx en Proxmox LXC es uno de los servicios autoalojados más útiles desde el primer día. La instalación toma menos de una hora y, una vez que el clasificador automático aprende de tus documentos, realmente se encarga de la mayor parte de la organización. La combinación de búsqueda con OCR, etiquetado automático y seguimiento de remitentes convierte una carpeta de escaneos caóticos en un archivo que de verdad puedes consultar.

El único punto débil en 2026: escanear desde el móvil todavía tiene un poco más de fricción que el flujo de escanear a una carpeta de Google Drive. Las apps móviles mejoraron, pero todavía no es perfecto. Aun así, todo lo demás de este stack, incluida la ausencia de costos por documento o dependencias de la nube, lo compensa de sobra.

Si ya usas Proxmox y quieres un LXC más que te devuelva valor todos los días, es este.

Aviso: este artículo contiene enlaces de afiliado. Si compras a través de ellos, puedo ganar una pequeña comisión sin costo extra para ti.