Instalación de Stirling-PDF: Herramientas PDF Self-Hosted

Stirling-PDF es una completa suite de herramientas para manipulación de PDF autoalojada que cubre todas las operaciones habituales: fusionar, dividir, comprimir, convertir, rotar, aplicar OCR, firmar digitalmente y más. Desplegado en tu propio servidor, procesa documentos de forma privada sin enviar archivos a servicios externos como ILovePDF o Smallpdf. Esta guía cubre la instalación de Stirling-PDF en Linux con Docker.

Requisitos Previos

Servidor con Ubuntu 20.04+, Debian 11+ o CentOS 8+
Docker y Docker Compose instalados
Mínimo 1 GB de RAM (2 GB recomendados para OCR)
Puerto 8080 disponible
Espacio en disco para procesamiento de PDFs temporales

Instalación con Docker

# Ejecutar Stirling-PDF con Docker
docker run -d \
  --name stirling-pdf \
  --restart unless-stopped \
  -p 8080:8080 \
  -v ~/stirling-pdf/trainingData:/usr/share/tessdata \
  -v ~/stirling-pdf/extraConfigs:/configs \
  -v ~/stirling-pdf/logs:/logs \
  -e DOCKER_ENABLE_SECURITY=false \
  -e INSTALL_BOOK_AND_ADVANCED_HTML_OPS=false \
  -e LANGS=es_ES \
  frooodle/s-pdf:latest

# Acceder al panel en http://TU-SERVIDOR:8080

Instalación con Docker Compose

mkdir -p ~/stirling-pdf && cd ~/stirling-pdf

cat > docker-compose.yml << 'EOF'
version: '3.3'

services:
  stirling-pdf:
    image: frooodle/s-pdf:latest
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      - 8080:8080
    volumes:
      - ./trainingData:/usr/share/tessdata  # Datos de entrenamiento OCR
      - ./extraConfigs:/configs             # Configuración adicional
      - ./logs:/logs                        # Logs de la aplicación
    environment:
      # Idiomas para OCR (descargar automáticamente los datos de idioma)
      LANGS: es_ES
      # Habilitar autenticación (true para producción)
      DOCKER_ENABLE_SECURITY: "false"
      # Instalar LibreOffice para conversiones avanzadas de Office a PDF
      INSTALL_BOOK_AND_ADVANCED_HTML_OPS: "false"
      # Zona horaria
      TZ: Europe/Madrid
      # Nombre del sistema en la interfaz
      SYSTEM_ROOTURIPATH: "/"
EOF

# Crear directorios
mkdir -p ~/stirling-pdf/{trainingData,extraConfigs,logs}

# Iniciar
docker compose up -d
docker compose logs -f stirling-pdf

Acceder a la interfaz en http://TU-SERVIDOR:8080.

Operaciones Disponibles

Stirling-PDF ofrece más de 50 operaciones organizadas en categorías:

Organización de Páginas

# Fusionar múltiples PDFs via API
curl -X POST http://localhost:8080/api/v1/general/merge-pdfs \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]" \
  -o fusionado.pdf

# Dividir un PDF por rangos de páginas
curl -X POST http://localhost:8080/api/v1/general/split-pdf-by-pages \
  -F "[email protected]" \
  -F "pageNumbers=1,5-10,15" \
  -o dividido.zip

# Extraer páginas específicas
curl -X POST http://localhost:8080/api/v1/general/remove-pages \
  -F "[email protected]" \
  -F "pageNumbers=2,4,6" \
  -o sin-paginas.pdf

# Rotar páginas
curl -X POST http://localhost:8080/api/v1/general/rotate-pdf \
  -F "[email protected]" \
  -F "angle=90" \
  -o rotado.pdf

Conversión de Formatos

# Convertir imagen a PDF
curl -X POST http://localhost:8080/api/v1/convert/img/pdf \
  -F "[email protected]" \
  -F "fitOption=fillPage" \
  -o imagen-a-pdf.pdf

# PDF a imagen (PNG)
curl -X POST http://localhost:8080/api/v1/convert/pdf/img \
  -F "[email protected]" \
  -F "imageFormat=png" \
  -F "singleOrMultiple=multiple" \
  -o paginas.zip

# Convertir HTML a PDF
curl -X POST http://localhost:8080/api/v1/convert/url/pdf \
  -F "urlInput=https://ejemplo.com/pagina" \
  -o pagina-web.pdf

# Convertir Word/Excel a PDF (requiere LibreOffice instalado)
# Activar en docker-compose: INSTALL_BOOK_AND_ADVANCED_HTML_OPS=true
curl -X POST http://localhost:8080/api/v1/convert/file/pdf \
  -F "[email protected]" \
  -o documento-convertido.pdf

Optimización y Compresión

# Comprimir un PDF (reducir tamaño)
curl -X POST http://localhost:8080/api/v1/general/compress-pdf \
  -F "[email protected]" \
  -F "optimizeLevel=2" \
  -o documento-comprimido.pdf
# Niveles: 1 (bajo), 2 (medio), 3 (alto), 4 (máximo)

# Reparar un PDF dañado
curl -X POST http://localhost:8080/api/v1/general/repair \
  -F "fileInput=@documento-dañado.pdf" \
  -o documento-reparado.pdf

Seguridad y Firmas

# Agregar contraseña a un PDF
curl -X POST http://localhost:8080/api/v1/security/add-password \
  -F "[email protected]" \
  -F "ownerPassword=contrasena-propietario" \
  -F "userPassword=contrasena-usuario" \
  -F "encryptionType=AES" \
  -o protegido.pdf

# Eliminar contraseña de un PDF
curl -X POST http://localhost:8080/api/v1/security/remove-password \
  -F "[email protected]" \
  -F "password=contrasena-correcta" \
  -o sin-contrasena.pdf

# Agregar marca de agua de texto
curl -X POST http://localhost:8080/api/v1/general/add-stamp \
  -F "[email protected]" \
  -F "stamp=CONFIDENCIAL" \
  -F "color=#FF0000" \
  -F "fontSize=30" \
  -F "rotation=45" \
  -F "opacity=0.3" \
  -o marcado.pdf

Configuración de OCR

Stirling-PDF usa Tesseract para OCR. Configurar los idiomas adicionales:

# Los datos de entrenamiento de Tesseract se descargan automáticamente
# Especificar idiomas en la variable de entorno LANGS

# Ver los datos de idioma disponibles
docker exec stirling-pdf ls /usr/share/tessdata/

# Descargar datos de idioma manualmente si falla la descarga automática
wget https://github.com/tesseract-ocr/tessdata/raw/main/spa.traineddata \
  -O ~/stirling-pdf/trainingData/spa.traineddata

# OCR via API
curl -X POST http://localhost:8080/api/v1/misc/ocr-pdf \
  -F "[email protected]" \
  -F "languages=spa" \
  -F "ocrType=skip-text" \
  -o documento-con-texto.pdf
# ocrType: skip-text (solo páginas sin texto), force-ocr (todo), auto

Opciones de OCR disponibles en la interfaz:

Idioma: Español, inglés, etc. (múltiples idiomas simultáneos)
Tipo OCR: Solo páginas sin texto / Forzar en todas / Automático
PDF/A: Generar PDF compatible con archivo a largo plazo

Uso de la API REST

Stirling-PDF tiene una API REST completa con documentación Swagger:

# Documentación interactiva de la API
# http://TU-SERVIDOR:8080/swagger-ui/index.html

# Verificar que la API está funcionando
curl http://localhost:8080/api/v1/info | python3 -m json.tool

# Script de ejemplo: procesar múltiples PDFs por lotes
#!/bin/bash
ENTRADA_DIR="/mnt/documentos/entrantes"
SALIDA_DIR="/mnt/documentos/procesados"
SERVIDOR="http://localhost:8080"

for pdf in "$ENTRADA_DIR"/*.pdf; do
  nombre=$(basename "$pdf" .pdf)
  
  echo "Procesando: $nombre"
  
  # Comprimir y aplicar OCR
  curl -s -X POST "$SERVIDOR/api/v1/misc/ocr-pdf" \
    -F "fileInput=@$pdf" \
    -F "languages=spa" \
    -F "ocrType=skip-text" \
    -o "/tmp/${nombre}-ocr.pdf"
  
  curl -s -X POST "$SERVIDOR/api/v1/general/compress-pdf" \
    -F "fileInput=@/tmp/${nombre}-ocr.pdf" \
    -F "optimizeLevel=2" \
    -o "$SALIDA_DIR/${nombre}-procesado.pdf"
  
  rm "/tmp/${nombre}-ocr.pdf"
  echo "  → Guardado: $SALIDA_DIR/${nombre}-procesado.pdf"
done

Configuración de Seguridad

Para entornos de producción, activar la autenticación:

# Editar docker-compose.yml para habilitar seguridad
environment:
  DOCKER_ENABLE_SECURITY: "true"
  SECURITY_ENABLELOGIN: "true"
  SECURITY_USERNAME: "admin"
  SECURITY_PASSWORD: "contrasena-muy-segura"
  # Deshabilitar registro de nuevos usuarios
  SECURITY_INITIALLOGIN_USERNAME: "admin"
  SECURITY_INITIALLOGIN_PASSWORD: "contrasena-muy-segura"

docker compose down && docker compose up -d

# Usar autenticación en las llamadas API
curl -X POST http://localhost:8080/api/v1/general/merge-pdfs \
  -u "admin:contrasena-muy-segura" \
  -F "[email protected]" \
  -F "[email protected]" \
  -o fusionado.pdf

# O con token de sesión (obtener primero haciendo login)
curl -X POST http://localhost:8080/api/v1/login \
  -d "username=admin&password=contrasena" | grep -i "set-cookie"

Proxy Inverso con Nginx

# Obtener certificado SSL
sudo certbot --nginx -d pdf.tu-dominio.com

# Configuración de Nginx para Stirling-PDF
sudo tee /etc/nginx/sites-available/stirling-pdf << 'EOF'
server {
    listen 443 ssl http2;
    server_name pdf.tu-dominio.com;

    ssl_certificate /etc/letsencrypt/live/pdf.tu-dominio.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/pdf.tu-dominio.com/privkey.pem;

    # Aumentar límite de subida para PDFs grandes
    client_max_body_size 500M;
    proxy_read_timeout 600s;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
}
EOF

sudo ln -s /etc/nginx/sites-available/stirling-pdf /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Solución de Problemas

Stirling-PDF no inicia:

# Ver logs del contenedor
docker logs stirling-pdf --tail 50

# Verificar que el puerto no está en uso
sudo ss -tlnp | grep 8080

# Reiniciar el contenedor
docker compose restart stirling-pdf

El OCR falla o no reconoce el idioma:

# Verificar los datos de idioma disponibles
docker exec stirling-pdf ls /usr/share/tessdata/ | grep -E "spa|eng"

# Si falta el archivo de idioma, descargarlo manualmente
wget https://github.com/tesseract-ocr/tessdata/raw/main/spa.traineddata
docker cp spa.traineddata stirling-pdf:/usr/share/tessdata/

Error al convertir documentos Office:

# LibreOffice debe estar instalado para conversiones de Office
# Activar en docker-compose.yml:
# INSTALL_BOOK_AND_ADVANCED_HTML_OPS: "true"
# Esto aumenta el tiempo de inicio y el tamaño de la imagen

docker compose down && docker compose up -d
# La primera vez tardará más en iniciar mientras instala LibreOffice

Conclusión

Stirling-PDF elimina la necesidad de servicios externos para el procesamiento de PDFs, garantizando que tus documentos nunca abandonan tu infraestructura. Con más de 50 operaciones disponibles vía interfaz web o API REST, y soporte para OCR multilingüe y conversión de formatos, es una herramienta esencial para cualquier entorno self-hosted que maneje documentación importante.

Stirling PDF Tools Installation

En esta página