Stirling-PDF es una suite web de herramientas para PDF que puedes autoalojar con Docker en un solo contenedor, sin depender de webs que suben tus documentos a servidores ajenos. En esta guía levantas la aplicación con un único archivo docker-compose.yml, entiendes qué puedes hacer con sus más de cincuenta herramientas, aprendes por qué el procesamiento local protege tu privacidad y ves cómo protegerla tras un inicio de sesión o un SSO. La misma explicación está disponible en inglés.

Puntos clave

  • Stirling-PDF es una aplicación de código abierto que reúne más de 50 herramientas para manipular PDF: unir, dividir, comprimir, convertir, firmar, redactar y aplicar OCR.
  • Se ejecuta como un contenedor único que escucha en el puerto 8080; no necesita base de datos externa para empezar.
  • Todo el procesamiento ocurre en tu servidor: los archivos se procesan y se descartan, no se almacenan ni se envían a terceros.
  • Hay tres variantes de imagen: latest (estándar), latest-fat (con fuentes y conversores extra) y latest-ultra-lite (solo el núcleo, ideal para una Raspberry Pi).
  • La última versión estable es la 2.14.2 (8 de julio de 2026); conviene fijar esa etiqueta y no usar :latest a ciegas.

¿Qué es Stirling-PDF?

Stirling-PDF es una aplicación web de código abierto que agrupa en un solo sitio casi todo lo que alguna vez has buscado en webs como «unir PDF» o «comprimir PDF». En lugar de subir documentos sensibles a un servicio desconocido, montas tú mismo la herramienta en tu servidor y trabajas con tus archivos sin que salgan de tu red. El propio repositorio se define como «the #1 PDF Application on GitHub», y esa popularidad se nota en el ritmo de nuevas funciones.

Por dentro es un servicio Java sobre Spring Boot (framework para construir aplicaciones Java empaquetadas como un único servicio) con un frontend en TypeScript, empaquetado en una única imagen de Docker. No necesita base de datos externa para arrancar: guarda su configuración en un volumen y procesa cada documento al vuelo. Esto lo convierte en uno de los servicios más fáciles de esta serie de self-hosting con Docker, porque una sola definición de servicio basta para tenerlo funcionando.

¿Qué herramientas ofrece: unir, dividir, OCR y firmar?

La gran ventaja de Stirling-PDF es que sustituye a decenas de webs sueltas por una sola interfaz. Sus más de cincuenta operaciones se agrupan en varias familias:

  • Organizar: unir varios PDF en uno, dividir por páginas o marcadores, reordenar, rotar y eliminar páginas.
  • Convertir: pasar de PDF a imagen y al revés, a y desde formatos de Office, o combinar imágenes en un PDF.
  • Seguridad: añadir o quitar contraseña, gestionar permisos, firmar digitalmente, redactar (tapar) texto y poner marcas de agua.
  • Optimizar y editar: comprimir para reducir el tamaño, editar metadatos, comparar dos documentos y reparar archivos dañados.
  • OCR: reconocer el texto de documentos escaneados para poder buscar y copiar, usando Tesseract (el motor de reconocimiento óptico de caracteres de código abierto que hay detrás de la función) con los idiomas que instales.

Además incluye un sistema de «pipelines» para encadenar varias operaciones y automatizarlas, útil si procesas lotes de documentos con el mismo tratamiento. La lista completa y actualizada vive en la documentación oficial, porque cada versión suele sumar herramientas nuevas.

El docker-compose.yml de Stirling-PDF

Crea una carpeta para el proyecto y guarda dentro este docker-compose.yml. Fija la etiqueta a una versión concreta (aquí 2.14.2) para controlar tú cuándo actualizas, y monta los volúmenes para que la configuración y los datos de OCR sobrevivan a un reinicio:

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:2.14.2
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./data/tessdata:/usr/share/tessdata
      - ./data/configs:/configs
      - ./data/logs:/logs
      - ./data/pipeline:/pipeline
    environment:
      DISABLE_ADDITIONAL_FEATURES: "false"
      SECURITY_ENABLELOGIN: "false"
      SYSTEM_DEFAULTLOCALE: "es-ES"
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8080/api/v1/info/status | grep -q 'UP'"]
      interval: 30s
      timeout: 10s
      retries: 5

restart: unless-stopped hace que Docker vuelva a levantar el contenedor tras un reinicio del host, y el bloque healthcheck consulta cada 30 segundos el endpoint /api/v1/info/status de la propia aplicación para marcarla como sana solo cuando responde UP. Arranca el contenedor y comprueba ese estado:

docker compose up -d
docker compose ps

Cuando el estado aparezca como healthy, abre http://localhost:8080 en el navegador y verás la pantalla principal con todas las herramientas organizadas por categorías. La variable SYSTEM_DEFAULTLOCALE fija el idioma de la interfaz (aquí español de España). La imagen solo trae instalado el paquete de OCR en inglés: para reconocer texto en español descarga también el fichero de idioma de Tesseract en la carpeta que has montado como tessdata, sin borrar el inglés, y reinicia el contenedor:

mkdir -p ./data/tessdata
curl -Lo ./data/tessdata/eng.traineddata https://github.com/tesseract-ocr/tessdata_fast/raw/main/eng.traineddata
curl -Lo ./data/tessdata/spa.traineddata https://github.com/tesseract-ocr/tessdata_fast/raw/main/spa.traineddata
docker compose restart stirling-pdf

Los datos de configuración y los paquetes de OCR se guardan en el bind mount ./data; si quieres entender bien la diferencia entre volúmenes con nombre y bind mounts, repasa la guía sobre volúmenes y bind mounts en Docker.

Ten en cuenta que la imagen estándar ocupa poco más de 1 GB en disco y conviene reservar unos 2 GB de RAM para trabajar con documentos grandes. Si tu servidor va justo de recursos, cambia la etiqueta por 2.14.2-ultra-lite para la variante ligera; si necesitas las mejores conversiones a Office, usa 2.14.2-fat.

¿Por qué el procesamiento local mejora la privacidad?

La razón principal para autoalojar Stirling-PDF es no entregar documentos privados (contratos, nóminas, escrituras) a una web gratuita cuya política de datos desconoces. Aquí el flujo es distinto: el archivo se sube a tu propio contenedor, se procesa en memoria y en el disco temporal, y el resultado se te devuelve. La herramienta no conserva copias ni manda nada fuera.

Esto encaja con la filosofía de esta serie: recuperar el control de tus datos. Si además quieres que Stirling-PDF no registre estadísticas de uso, pon SYSTEM_ENABLEANALYTICS a false en el bloque environment. Para empezar desde cero necesitas Docker instalado; si es tu caso, sigue primero la guía para instalar Docker en Ubuntu 24.04.

¿Cómo publicarlo protegido tras autenticación?

Servir Stirling-PDF en abierto dentro de tu red local está bien para pruebas, pero exponerlo a Internet sin protección es una mala idea: cualquiera con la URL podría usar tu servidor para procesar sus archivos. Hay dos capas de protección que puedes combinar.

La primera es el inicio de sesión propio de la aplicación. Cambia SECURITY_ENABLELOGIN a true y recrea el contenedor; Stirling-PDF creará un usuario administrador inicial (por defecto admin con contraseña stirling) que debes cambiar en cuanto entres. Desde ahí puedes crear más usuarios y controlar quién accede.

La segunda, más robusta para un servicio expuesto, es colocarlo detrás de un proxy inverso con inicio de sesión único. Con Authentik como proveedor de SSO delante del contenedor, obligas a autenticarte antes de llegar siquiera a la interfaz de Stirling-PDF, y reutilizas los mismos usuarios que en el resto de tu infraestructura. Es el patrón recomendado cuando el servicio sale a Internet.

Preguntas frecuentes

¿Stirling-PDF necesita una base de datos?

No para empezar. La imagen estándar guarda su configuración y sus usuarios en H2 (una base de datos ligera que corre embebida dentro del propio proceso Java, sin servidor aparte) dentro de /configs, tanto si activas SECURITY_ENABLELOGIN como si no. Solo si tienes licencia Enterprise puedes apuntar la aplicación a un PostgreSQL (sistema de bases de datos relacional) externo propio; para el uso doméstico o de equipo que cubre esta guía, H2 es más que suficiente y no necesitas levantar ningún contenedor de base de datos aparte.

¿Por qué no debo usar la etiqueta latest de la imagen?

Porque :latest cambia sin avisarte y una actualización mayor podría alterar la configuración o el comportamiento durante un simple reinicio. Al fijar stirlingtools/stirling-pdf:2.14.2 decides tú cuándo actualizas: lees primero las notas de la versión, haces una copia de tu carpeta ./data y solo entonces subes la etiqueta. La 2.14.2, publicada el 8 de julio de 2026, es un parche de estabilidad sobre la 2.14.0, que sí trajo cambios de peso como la firma con token de hardware (tarjeta o llave USB) en la app de escritorio.

¿Se guardan mis documentos en el servidor?

No. Stirling-PDF procesa cada archivo y devuelve el resultado sin conservar copias permanentes de tus documentos. Por eso es una alternativa privada a las webs de PDF: los datos nunca salen de tu servidor. El volumen ./data solo almacena la configuración, los logs y los paquetes de idioma de OCR, no tus PDF.

Conclusión

Con un único docker-compose.yml tienes una navaja suiza de PDF completa y privada: más de cincuenta herramientas para unir, dividir, convertir, firmar y aplicar OCR, todo procesado en tu propio servidor. El siguiente paso lógico es fijar una versión concreta, montar los volúmenes de configuración y OCR, y decidir cómo protegerla: con el inicio de sesión propio para uso doméstico o detrás de Authentik si la sacas a Internet. A partir de ahí, deja de subir tus documentos a webs ajenas y hazlo todo en casa.

Fuentes

  1. Documentación oficial de Stirling-PDF
  2. Repositorio Stirling-Tools/Stirling-PDF en GitHub
  3. Imagen oficial stirlingtools/stirling-pdf en Docker Hub
  4. Guía oficial de base de datos externa de Stirling-PDF

Ruta: Productividad y documentos self-hosted con Docker