Stirling PDF Docker Compose

Stirling PDF Docker Compose es la solución definitiva para editar, convertir y gestionar documentos PDF sin depender de servicios en la nube. En esta guía completa, aprenderás a desplegar Stirling PDF de manera profesional con Docker Compose, configurar más de 60 herramientas PDF avanzadas, y procesar tus documentos de forma 100% privada sin enviar archivos a terceros. Descubre cómo transformar tu servidor en una suite completa de edición PDF con autenticación, OCR y conversión de formatos.

¿Qué es Stirling PDF?

Stirling PDF es una plataforma de código abierto para la edición y manipulación de documentos PDF que cuenta con más de 70.000 estrellas en GitHub, convirtiéndose en el proyecto PDF más popular de la comunidad. A diferencia de las soluciones en la nube como Smallpdf o ILovePDF, Stirling PDF te permite procesar documentos de manera completamente local, garantizando la privacidad total de tu información sensible.

Esta herramienta ofrece más de 60 funciones especializadas que incluyen edición de contenido, fusión y división de archivos, firma digital, redacción de información confidencial, conversión entre formatos (Word, Excel, PowerPoint, imágenes), reconocimiento óptico de caracteres (OCR), compresión inteligente, y automatización mediante APIs REST. Todo ello accesible desde una interfaz web moderna disponible en más de 40 idiomas.

El proyecto está construido con Java y TypeScript, utiliza LibreOffice para conversiones de documentos y Tesseract para OCR. Su arquitectura modular permite elegir entre diferentes variantes de imagen Docker según tus necesidades: latest para uso estándar, latest-fat con fuentes adicionales y funciones de seguridad extendidas, o latest-ultra-lite para entornos con recursos limitados.

Arquitectura de Stirling PDF Docker Compose

La implementación de Stirling PDF Docker Compose utiliza una arquitectura basada en contenedores que simplifica enormemente el despliegue. El sistema consta de un único contenedor que encapsula todos los componentes necesarios: el motor de procesamiento PDF basado en Java, el servidor web integrado, las bibliotecas de LibreOffice para conversión de documentos, y Tesseract para reconocimiento óptico de caracteres.

Esta arquitectura monolítica dentro del contenedor ofrece ventajas significativas en cuanto a simplicidad de gestión y consumo de recursos. El contenedor expone el puerto 8080 por defecto, donde se sirve la interfaz web completa. Los archivos de configuración, logs y datos temporales se almacenan en un volumen persistente montado en /configs, lo que permite mantener la configuración entre reinicios del contenedor.

Para despliegues empresariales, Stirling PDF soporta arquitecturas distribuidas donde frontend y backend pueden escalarse independientemente, permitiendo balanceo de carga y alta disponibilidad. Además, el sistema puede integrarse con proveedores de autenticación externos mediante SSO (Single Sign-On) para centralizar la gestión de usuarios en organizaciones grandes.

Requisitos Previos

Antes de instalar Stirling PDF Docker Compose, asegúrate de cumplir con los siguientes requisitos técnicos en tu servidor:

Docker Engine: Versión 20.10 o superior instalada y funcionando correctamente
Docker Compose: Versión 2.0 o posterior (se recomienda usar Docker Compose V2)
Hardware mínimo: 2GB de RAM, 2 núcleos de CPU, y 5GB de espacio en disco para la imagen y datos temporales
Sistema operativo: Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+), Windows con WSL2, o macOS
Puertos disponibles: Puerto 8080 libre (o el puerto que elijas configurar)
Acceso a internet: Para descargar la imagen Docker desde Docker Hub

Para verificar que Docker está instalado correctamente, ejecuta docker --version y docker compose version en tu terminal. Si necesitas instalar Docker, consulta la documentación oficial de Docker para tu sistema operativo.

Instalar Stirling PDF Docker Compose Paso a Paso

La instalación de Stirling PDF Docker Compose es directa y puede completarse en menos de 5 minutos. Sigue estos pasos detallados para tener tu instancia funcionando:

Paso 1: Crear la Estructura de Directorios

Primero, crea un directorio dedicado para Stirling PDF y navega hasta él:

mkdir -p ~/stirling-pdf
cd ~/stirling-pdf
mkdir -p configs logs

Paso 2: Crear el Archivo docker-compose.yml

Crea el archivo de configuración con el siguiente contenido optimizado:

version: '3.8'

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    ports:
      - "8080:8080"
    volumes:
      - ./configs:/configs
      - ./logs:/logs
    environment:
      # Configuración básica
      - DOCKER_ENABLE_SECURITY=false
      - INSTALL_BOOK_AND_ADVANCED_HTML_OPS=false
      - LANGS=es_ES,en_US

      # Autenticación (deshabilitada por defecto)
      # - SECURITY_ENABLE_LOGIN=true
      # - SECURITY_INITIALLOGIN_USERNAME=admin
      # - SECURITY_INITIALLOGIN_PASSWORD=admin123

      # Límites de archivos
      - MAX_FILE_SIZE=1000
      - METRICS_ENABLED=true
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/api/v1/info/status"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Paso 3: Iniciar el Contenedor

Levanta el servicio con Docker Compose:

docker compose up -d

Verifica que el contenedor está ejecutándose correctamente:

docker compose ps
docker compose logs -f stirling-pdf

Paso 4: Acceder a la Interfaz Web

Abre tu navegador y accede a http://tu-servidor:8080. Deberías ver la interfaz principal de Stirling PDF con todas las herramientas disponibles organizadas por categorías: Editar, Convertir, Seguridad, Organizar, y más.

Configurar Stirling PDF Docker Compose con Autenticación

Para proteger tu instancia de Stirling PDF Docker Compose con autenticación de usuarios, modifica el archivo docker-compose.yml para habilitar el sistema de login:

environment:
  - DOCKER_ENABLE_SECURITY=true
  - SECURITY_ENABLE_LOGIN=true
  - SECURITY_INITIALLOGIN_USERNAME=admin
  - SECURITY_INITIALLOGIN_PASSWORD=MiPasswordSeguro123!
  - SECURITY_ENABLELOGIN_DEFAULTROLE=USER

  # OAuth2/OIDC (opcional)
  # - SECURITY_OAUTH2_ENABLED=true
  # - SECURITY_OAUTH2_CLIENT_ID=tu_client_id
  # - SECURITY_OAUTH2_CLIENT_SECRET=tu_client_secret
  # - SECURITY_OAUTH2_ISSUER=https://auth.tuempresa.com
  # - SECURITY_OAUTH2_PROVIDER=keycloak

Después de realizar los cambios, reinicia el contenedor con docker compose down && docker compose up -d. Al acceder nuevamente, se te pedirá usuario y contraseña. El usuario administrador inicial podrá crear cuentas adicionales desde el panel de configuración.

Para integraciones empresariales, Stirling PDF soporta OAuth2 y OIDC, permitiendo autenticación centralizada con Keycloak, Authentik, o Azure AD. Consulta la documentación oficial de Stirling PDF para configuraciones avanzadas de SSO.

Integrar Proxy Inverso con SSL

Para exponer Stirling PDF a internet de forma segura con HTTPS, te recomiendo usar Nginx Proxy Manager o Traefik. Aquí te muestro cómo integrarlo con Nginx Proxy Manager:

Configuración con Nginx Proxy Manager

Si ya tienes Nginx Proxy Manager Docker Compose instalado, sigue estos pasos:

Accede al panel de Nginx Proxy Manager (normalmente en puerto 81)
Ve a «Proxy Hosts» y haz clic en «Add Proxy Host»
Configura el dominio (ejemplo: pdf.tudominio.com)
En «Forward Hostname / IP» pon stirling-pdf (nombre del contenedor)
En «Forward Port» pon 8080
Habilita «Websockets Support»
En la pestaña SSL, solicita un certificado Let’s Encrypt

Asegúrate de que ambos contenedores estén en la misma red Docker para que puedan comunicarse. Si usas redes personalizadas, actualiza tu docker-compose.yml:

networks:
  proxy_network:
    external: true

services:
  stirling-pdf:
    # ... resto de configuración
    networks:
      - proxy_network

Gestión Avanzada con Stirling PDF Docker Compose

Una vez que tu instancia de Stirling PDF Docker Compose está funcionando, puedes aprovechar funciones avanzadas para maximizar su utilidad:

Automatización mediante API REST

Stirling PDF expone una API REST completa documentada en Scalar Registry que permite automatizar tareas de procesamiento PDF. Por ejemplo, para fusionar PDFs mediante curl:

curl -X POST http://localhost:8080/api/v1/merge \
  -F "[email protected]" \
  -F "[email protected]" \
  --output documento_fusionado.pdf

Configuración de OCR Multiidioma

Para habilitar OCR en español y otros idiomas, usa la imagen latest-fat que incluye paquetes de idiomas adicionales de Tesseract:

image: stirlingtools/stirling-pdf:latest-fat

environment:
  - OCR_AUTO_DETECT_LANG=true
  - OCR_LANGUAGES=spa,eng,fra,deu

Pipelines de Procesamiento sin Código

La funcionalidad de Pipelines permite crear flujos de trabajo complejos sin programar. Desde la interfaz web, puedes encadenar operaciones como «Convertir a PDF → Comprimir → Añadir marca de agua → Cifrar» y guardar este pipeline para reutilizarlo con un solo clic.

Optimización y Best Practices

Seguridad

Habilita autenticación: Nunca expongas Stirling PDF públicamente sin login
Usa contraseñas fuertes: Cambia las credenciales por defecto inmediatamente
Implementa SSL/TLS: Siempre accede mediante HTTPS con certificados válidos
Configura firewall: Restringe el acceso al puerto 8080 solo desde tu proxy inverso
Actualiza regularmente: Stirling PDF publica actualizaciones frecuentes con correcciones de seguridad

Rendimiento

Límites de recursos: Define límites de CPU y memoria en docker-compose.yml para evitar consumo excesivo
Límite de tamaño de archivo: Ajusta MAX_FILE_SIZE según tus necesidades (en MB)
Limpieza automática: Los archivos temporales se eliminan automáticamente tras el procesamiento
Métricas: Habilita METRICS_ENABLED=true para monitorizar el uso

services:
  stirling-pdf:
    # ... resto de configuración
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 4G
        reservations:
          cpus: '1.0'
          memory: 2G

Backups

Para respaldar tu configuración de Stirling PDF, simplemente copia el directorio configs:

#!/bin/bash
# Script de backup automático
BACKUP_DIR="/backups/stirling-pdf"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p "$BACKUP_DIR"
tar -czf "$BACKUP_DIR/stirling-pdf-config-$DATE.tar.gz" \
  -C ~/stirling-pdf configs/

# Mantener solo los últimos 7 backups
find "$BACKUP_DIR" -name "stirling-pdf-config-*.tar.gz" \
  -mtime +7 -delete

Programa este script con cron para ejecutarlo diariamente: 0 2 * * * /ruta/al/script-backup.sh

Troubleshooting Stirling PDF Docker Compose

Error: «Container continually restarts»

Causa: Permisos incorrectos en el volumen montado o puerto ya en uso.

Solución:

# Verifica los logs
docker compose logs stirling-pdf

# Comprueba que el puerto 8080 está libre
sudo netstat -tlnp | grep 8080

# Corrige permisos del directorio configs
sudo chown -R 1000:1000 ~/stirling-pdf/configs

Error: «OCR no funciona correctamente»

Causa: Usando imagen latest sin paquetes de idiomas completos.

Solución: Cambia a la imagen latest-fat que incluye todos los idiomas de Tesseract:

image: stirlingtools/stirling-pdf:latest-fat

Error: «Failed to convert Office documents»

Causa: LibreOffice necesita más tiempo de inicialización o memoria insuficiente.

Solución:

environment:
  - INSTALL_BOOK_AND_ADVANCED_HTML_OPS=true

deploy:
  resources:
    limits:
      memory: 4G

Error: «Cannot login after enabling authentication»

Causa: Credenciales mal configuradas o base de datos corrupta.

Solución: Resetea la configuración de autenticación eliminando el archivo de base de datos:

docker compose down
rm ~/stirling-pdf/configs/settings.db
docker compose up -d

Comandos de Diagnóstico Útiles

# Verificar estado del health check
docker inspect stirling-pdf | grep -A 10 Health

# Monitorizar uso de recursos en tiempo real
docker stats stirling-pdf

# Verificar conectividad de red
docker compose exec stirling-pdf curl -I http://localhost:8080

# Ver variables de entorno activas
docker compose exec stirling-pdf env | grep -i security

Conclusión

Implementar Stirling PDF Docker Compose en tu infraestructura te proporciona una solución profesional y privada para procesar documentos PDF sin depender de servicios externos. Con más de 60 herramientas integradas, desde edición básica hasta automatización mediante APIs, Stirling PDF se posiciona como la alternativa autohospedada más completa del mercado.

La instalación mediante Docker Compose simplifica enormemente el despliegue y mantenimiento, permitiéndote tener un sistema de procesamiento PDF empresarial funcionando en menos de 5 minutos. Las opciones de autenticación, integración con proxies inversos, y soporte para OCR multiidioma lo convierten en una herramienta versátil apta tanto para uso personal como corporativo.

Te recomiendo explorar las funcionalidades de pipelines y la API REST para automatizar tareas repetitivas de procesamiento de documentos. Si administras múltiples servicios autohospedados, integra Stirling PDF con tu stack existente de Docker Compose para centralizar la gestión de contenedores.

FAQ sobre Stirling PDF Docker Compose

¿Cuántos recursos necesita Stirling PDF?

La imagen latest estándar requiere aproximadamente 500MB de espacio en disco, 1GB de RAM para funcionamiento básico, y 2GB de RAM para operaciones intensivas como OCR en documentos grandes. Para uso empresarial con múltiples usuarios concurrentes, se recomienda asignar 4GB de RAM y 2 núcleos de CPU.

¿Puedo usar Stirling PDF sin Docker?

Sí, Stirling PDF ofrece también versiones de escritorio para Windows, Linux y macOS descargables desde su repositorio de GitHub. Sin embargo, la versión Docker Compose es la más recomendada para servidores por su facilidad de actualización y gestión.

¿Cómo actualizo Stirling PDF a la última versión?

Actualizar es muy sencillo con Docker Compose. Ejecuta estos comandos desde el directorio de instalación:

docker compose pull
docker compose down
docker compose up -d

Esto descargará la última imagen disponible y recreará el contenedor manteniendo tu configuración intacta en el volumen configs.

¿Es seguro usar Stirling PDF para documentos confidenciales?

Sí, absolutamente. A diferencia de servicios en la nube, todos los archivos se procesan localmente en tu servidor y se eliminan automáticamente después de completar las operaciones. Ningún documento se envía a servidores externos. Para mayor seguridad, habilita autenticación, usa HTTPS, y mantén el software actualizado.

¿Stirling PDF soporta procesamiento por lotes?

Sí, la interfaz web permite subir múltiples archivos simultáneamente para operaciones como fusión, compresión o conversión. Además, la API REST puede integrarse con scripts para automatizar el procesamiento masivo de documentos utilizando herramientas como Bash, Python o n8n Docker Compose para workflows avanzados.