↓ Ir al contenido
Homelab.es
  1. Posts/

Stirling PDF: deja de subir tus documentos a ilovepdf y ponlo en tu homelab

·1519 palabras·8 mins
self hosting Pdf Stirling Docker Privacidad Self-Hosting
Tabla de contenido

Hace unos meses me di cuenta de que subía documentos de trabajo a ilovepdf casi cada semana. Contratos, facturas, presupuestos. Todo pasando por servidores que no controlo. No es que sea un paranoico de la privacidad, pero hay cosas que preferirías no tener en servidores de terceros.

Así llegué a Stirling PDF. Lleva un tiempo en GitHub con bastante tracción, lo había visto mencionado en varios hilos de Reddit, y un día me senté a instalarlo. Lleva meses funcionando sin problemas y lo uso casi a diario. Esto es lo que he aprendido.

Qué es Stirling PDF
#

Stirling PDF es una herramienta web self-hosted para manipular archivos PDF. Lo que ofrecen servicios como ilovepdf, smallpdf o Adobe online lo puedes hacer desde tu servidor, sin que el documento salga de tu red.

Tiene más de 50 operaciones diferentes: unir PDFs, dividirlos, comprimir, convertir a Word o Excel, rotar páginas, añadir marcas de agua, proteger con contraseña, eliminar contraseñas, extraer imágenes, reconocimiento de texto OCR, y bastante más. Todo desde una interfaz web limpia que funciona bien desde el móvil también.

Lo más importante desde mi punto de vista: procesa todo en local. El PDF nunca sale de tu servidor. Para documentos de empresa eso cambia mucho las cosas.

Por qué no usar los servicios online
#

Los servicios gratuitos de PDF no son malos, y los uso para cosas sin importancia. El problema es que no sabes exactamente qué hacen con los archivos que subes. La mayoría tiene políticas que dicen que eliminan los archivos pasadas unas horas, pero no puedes verificarlo.

Stirling PDF elimina esa variable. El archivo va a tu servidor, se procesa, lo descargas, y listo. Ni rastros ni logs de lo que has procesado.

Hay otra ventaja práctica: no hay límites de tamaño ni de número de operaciones por día. Los servicios gratuitos suelen limitarte bastante en ambas cosas.

Instalación con Docker Compose
#

La instalación es muy directa. Crea un directorio para el proyecto y un archivo docker-compose.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

version: '3.3'
services:
  stirling-pdf:
    image: frooodle/s-pdf:latest
    ports:
      - '8180:8080'
    volumes:
      - ./trainingData:/usr/share/tessdata
      - ./extraConfigs:/configs
      - ./logs:/logs
    environment:
      - DOCKER_ENABLE_SECURITY=false
      - INSTALL_BOOK_AND_ADVANCED_HTML_OPS=false
      - LANGS=spa_ES
    restart: unless-stopped

Uso el puerto 8180 porque el 8080 ya lo tengo ocupado. Ajusta según lo que tengas libre.

El volumen trainingData es para los datos de Tesseract, el motor de OCR. Si quieres reconocimiento de texto en español, necesitas descargar el modelo de idioma. Lo explico más abajo.

Arranca el contenedor:

1

docker compose up -d

En unos segundos tienes la interfaz disponible en http://tu-servidor:8180.

Configurar OCR en español
#

Por defecto el reconocimiento de texto funciona solo en inglés. Para añadir español hay que descargar el modelo correspondiente de Tesseract.

Entra al contenedor:

1

docker exec -it stirling-pdf bash

Y descarga el modelo de español:

1
2

cd /usr/share/tessdata
wget https://github.com/tesseract-ocr/tessdata_best/raw/main/spa.traineddata

Sal del contenedor y reinicia:

1

docker compose restart

A partir de ahí puedes hacer OCR en documentos en español y los resultados son bastante buenos. No perfecto con fuentes raras o documentos muy degradados, pero para facturas y contratos estándar funciona bien.

Detrás de un reverse proxy
#

No recomiendo dejar Stirling expuesto directamente sin autenticación si lo tienes accesible desde fuera de tu red. Hay dos opciones:

Opción 1: autenticación básica de Nginx Proxy Manager. Añades una capa de autenticación HTTP delante. Sencillo y funciona.

Opción 2: autenticación integrada de Stirling. Tiene su propio sistema de usuarios y roles. Actívalo con estas variables de entorno:

1
2
3

environment:
  - DOCKER_ENABLE_SECURITY=true
  - SECURITY_ENABLE_LOGIN=true

Yo uso la segunda opción porque me permite tener usuarios separados. Mi mujer usa Stirling también para cosas del trabajo y así no compartimos credenciales.

Para exponerlo con Cloudflare Tunnels, el proceso es igual que con cualquier otro servicio. Añades un nuevo hostname en el túnel apuntando a localhost:8180 y listo. Puedes leer cómo configurar Cloudflare Tunnels en este post que escribí hace unas semanas.

Las operaciones que uso más
#

Después de varios meses usando Stirling a diario, hay unas pocas operaciones que uso más del 80% del tiempo:

Merge PDF. Juntar varios documentos en uno. Uso esto constantemente para combinar páginas de diferentes fuentes antes de enviar algo.

Split PDF. Extraer páginas concretas de un documento más largo. Útil cuando recibes un PDF con 40 páginas y necesitas mandar solo las 3 relevantes.

Compress PDF. Reducir el tamaño de archivos para enviar por email. Los PDFs de algunas aplicaciones de diseño pesan un disparate. Con compresión media suelen quedar en la décima parte sin perder calidad visible.

PDF to Word. Convertir contratos y presupuestos de PDF a Word para editar. No es perfecto, especialmente con layouts complejos, pero para documentos con texto lineal funciona muy bien.

OCR PDF. Tengo varios documentos escaneados de años atrás que no tienen texto seleccionable. Con OCR los convierto a PDF con texto, lo que los hace buscables y mucho más útiles.

Add password. Proteger PDFs con contraseña antes de enviarlos por email.

Automatización con la API
#

Stirling tiene una API REST que permite automatizar operaciones sin usar la interfaz web. Esto es lo que me parece más interesante para integrarlo en flujos de trabajo.

Por ejemplo, para comprimir un PDF desde línea de comandos:

1
2
3
4
5
6

curl -X POST \
  http://tu-servidor:8180/api/v1/general/compress-pdf \
  -H "Content-Type: multipart/form-data" \
  -F "[email protected]" \
  -F "optimizeLevel=2" \
  --output documento-comprimido.pdf

Tengo un script que coge los PDFs que entran en una carpeta específica, los comprime automáticamente y los mueve a otra carpeta. Con n8n o cualquier sistema de automatización puedes montar workflows más elaborados.

La documentación de la API está en http://tu-servidor:8180/swagger-ui/index.html. No está al nivel de las mejores APIs que he visto, pero cubre lo necesario.

Rendimiento y recursos
#

He estado mirando el consumo durante estas semanas y los números son buenos. En reposo consume prácticamente nada. Procesando un PDF normal de 10-15 páginas sube a 200-300 MB de RAM y un 20-30% de CPU durante unos segundos, luego vuelve a cero.

Para operaciones pesadas como OCR en documentos largos o conversiones de muchas páginas, el proceso puede tardar varios segundos. Nada que sea un problema en la práctica.

En mi servidor corre junto a otras 30 aplicaciones sin causar problemas. Un mini PC básico con 4 GB de RAM lo mueve sin estrés.

Limitaciones que he encontrado
#

Siendo honesto con lo que no funciona tan bien:

Conversiones complejas. PDF a Word en documentos con tablas elaboradas, columnas múltiples o formatos complejos no siempre queda bien. El texto se extrae, pero el formato se pierde. Para documentos simples funciona estupendamente.

Algunas conversiones avanzadas. La opción de convertir HTML a PDF requiere instalar dependencias adicionales que no están en la imagen por defecto. Se puede hacer, pero necesita pasos extras.

Procesamiento masivo. Si necesitas procesar cientos de archivos a la vez, la interfaz web no es el camino. Hay que tirar de la API y preparar scripts. No es un defecto del proyecto, es que está diseñado para uso interactivo principalmente.

Actualizaciones frecuentes. El proyecto está muy activo y saca nuevas versiones constantemente. Esto es bueno porque el software mejora, pero hay que estar al tanto. Con Watchtower puedes automatizar las actualizaciones si no te importa que a veces una actualización venga con algún cambio inesperado.

Comparativa con los servicios de pago
#

No voy a mentir: ilovepdf y smallpdf tienen interfaces pulidas y están muy optimizadas para usuarios que no quieren complicaciones. Si lo único que haces es juntar dos PDFs una vez al mes, quizás no tiene sentido montar esto.

Pero si tu trabajo implica manejar documentos regularmente, el cálculo cambia. Adobe Acrobat cuesta bastante al año. ilovepdf Pro son unos 50-60€ anuales para uso profesional. Stirling no te cuesta nada más allá del hardware que ya tienes.

Y el factor privacidad para mí no es negociable cuando hablamos de documentos de empresa.

Integración con otros servicios del homelab
#

Una cosa que me gusta de Stirling es que encaja bien con Paperless-ngx, que ya tenía funcionando. El flujo que tengo montado es:

  1. Los documentos entran como archivos sueltos o por correo a Paperless
  2. Paperless los indexa y hace OCR automático
  3. Si necesito manipular alguno manualmente, lo exporto de Paperless, lo proceso en Stirling, y lo vuelvo a importar

No es un flujo perfecto porque son dos herramientas separadas, pero cubre todos los casos que me aparecen.

Si no tienes Paperless montado todavía, escribí sobre él hace unas semanas y lo explico en detalle: Paperless-ngx: digitaliza y organiza tus documentos.

Conclusión
#

Stirling PDF es uno de esos proyectos que te preguntas por qué no lo instalaste antes. Cumple exactamente lo que promete, no tiene complicaciones, consume pocos recursos y resuelve un problema real.

Si manejas documentos con cierta frecuencia y tienes cualquier servidor en casa, aunque sea una Raspberry Pi, merece la pena instalarlo. La instalación son literalmente cinco minutos.

Lo único que me queda pendiente es montar un flujo de automatización más elaborado usando la API, pero eso ya es optimizar algo que ya funciona bien.