Cómo Autoalojar Stirling PDF (Docker, Traefik, Dokploy)

Los documentos PDF están en todas partes: contratos, facturas, informes, formularios escaneados. Manipularlos suele significar pagar por Acrobat Pro, subir archivos a alguna herramienta web de terceros o improvisar con utilidades de línea de comandos que funcionan a medias.

Stirling PDF es una aplicación web autoalojada que permite unir, dividir, convertir, comprimir, aplicar OCR, firmar y docenas de operaciones más sobre PDF, todo ejecutándose en tu propia infraestructura. El proyecto alcanzó la V2 a finales de 2025 con una reescritura completa del frontend en React, deshacer/rehacer con estado, aplicaciones de escritorio, un servidor MCP integrado para agentes de IA y Automate/Pipelines para encadenar operaciones. Cuenta con más de 91.000 estrellas en GitHub y más de 30 millones de descargas. El nivel autoalojado gratuito admite hasta 5 usuarios sin restricciones de funciones en las operaciones.

Esta guía recorre tres rutas de despliegue: Docker Compose independiente, Traefik con Dockge y Dokploy. Cada una se puede copiar y pegar e incluye pasos de verificación.

Para más aplicaciones autoalojadas útiles, consulta nuestra guía sobre contenedores Docker para servidores domésticos.

¿Qué es Stirling PDF?

Stirling PDF es una plataforma PDF autoalojada de núcleo abierto (open-core). El nivel gratuito te da acceso completo a más de 60 herramientas, sin créditos, sin marcas de agua y sin límites artificiales en el número de operaciones. Se ejecuta como un único contenedor Docker con un backend de procesamiento en Java, frontend en React e integraciones opcionales para Tesseract OCR, LibreOffice y PDFium.

Capacidades clave de Stirling PDF

Cómo funciona Stirling PDF

Stirling PDF es un proyecto de código abierto. Consulta la documentación y contribuye en el repositorio de GitHub y el sitio web del proyecto. La documentación completa está en docs.stirlingpdf.com.

Licencias: gratuita, servidor y empresarial

Stirling PDF pasó a un modelo open-core. El desglose para quienes se autoalojan:

Para un operador en solitario o un equipo pequeño, el nivel gratuito es todo lo que necesitas. Los niveles de pago importan cuando necesitas SSO o soporte de base de datos externa.

Requisitos previos

Antes de desplegar Stirling PDF, asegúrate de contar con lo siguiente:

Variantes de imagen:

Requisitos de infraestructura:

• Servidor: Un VPS o servidor dedicado. Hetzner VPS o Hostinger VPS funcionan bien para esto. Para instalación local, consulta mini PCs para servidores domésticos.
• Docker Engine: Última versión estable con Docker Compose v2
• Proxy inverso (para HTTPS): Configura un proxy inverso Traefik en Docker o usa Caddy. Para certificados SSL, sigue la guía de certificado wildcard de Traefik.
• Gestión de contenedores (opcional): Dockge para gestionar stacks o Dokploy para una plataforma completa
• Dominio: Un subdominio apuntando a tu servidor (p. ej., pdf.yourdomain.com)
• Firewall: Puerto 8080 para instalación independiente, o 443 vía proxy inverso

Los precios de los VPS subieron en general en 2026 — si estás reconsiderando un servidor alquilado, consulta qué cambió y cuándo gana un mini PC.

Opción de instalación 1: Docker y Docker Compose (independiente)

Esta es la ruta más sencilla. Un único contenedor, sin proxy inverso, ideal para acceso en red local o pruebas antes de añadir HTTPS.

Paso 1: Crear la estructura del proyecto

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

Paso 2: Configurar Docker Compose

Crea un archivo docker-compose.yml:

services:
  stirling-pdf:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    ports:
      - "8080:8080"
    volumes:
      - ./stirling-data/tessdata:/usr/share/tessdata    # OCR language files
      - ./stirling-data/configs:/configs                # settings.yml + H2 DB (back this up!)
      - ./stirling-data/logs:/logs
      - ./stirling-data/customFiles:/customFiles
      - ./stirling-data/pipeline:/pipeline              # Automate / folder-scan configs
    environment:
      - SECURITY_ENABLELOGIN=true                       # login is ON by default
      - SECURITY_INITIALLOGIN_USERNAME=admin            # optional, first boot only
      - SECURITY_INITIALLOGIN_PASSWORD=ChangeMeNow123!  # optional, first boot only
      - SYSTEM_DEFAULTLOCALE=en-US                      # UI language (hyphenated)
      - SYSTEM_GOOGLEVISIBILITY=false                   # block search engine indexing
      - SYSTEM_MAXFILESIZE=500                          # per-file MB (1-999)
      - SPRING_SERVLET_MULTIPART_MAX_FILE_SIZE=2000MB
      - SPRING_SERVLET_MULTIPART_MAX_REQUEST_SIZE=2000MB
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/api/v1/info/status"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

Para acceso anónimo (sin inicio de sesión), establece SECURITY_ENABLELOGIN=false y DISABLE_ADDITIONAL_FEATURES=false.

Paso 3: Inicializar los directorios y desplegar

mkdir -p stirling-data/{tessdata,configs,logs,customFiles,pipeline}
docker compose up -d

Observa los registros para confirmar el arranque:

docker compose logs -f

Busca Started StirlingPDF en la salida. Si ves advertencias de unknown configuration key, son variables de entorno obsoletas. Inofensivas pero ruidosas. Elimínalas de tu archivo compose.

Paso 4: Configurar el soporte OCR (opcional)

Descarga los paquetes de idioma de Tesseract para OCR:

# English is required. Do not delete eng.traineddata
wget -P stirling-data/tessdata/ https://github.com/tesseract-ocr/tessdata/raw/main/eng.traineddata
wget -P stirling-data/tessdata/ https://github.com/tesseract-ocr/tessdata/raw/main/fra.traineddata
wget -P stirling-data/tessdata/ https://github.com/tesseract-ocr/tessdata/raw/main/deu.traineddata
wget -P stirling-data/tessdata/ https://github.com/tesseract-ocr/tessdata/raw/main/spa.traineddata
wget -P stirling-data/tessdata/ https://github.com/tesseract-ocr/tessdata/raw/main/chi_sim.traineddata

Reinicia el contenedor después de añadir los archivos de idioma:

docker compose restart stirling-pdf

Paso 5: Verificar la instalación

• Interfaz web: Navega a http://localhost:8080
• Comprobación de salud: curl http://localhost:8080/api/v1/info/status
• Documentación API: Visita http://localhost:8080/swagger-ui.html

Fallo común: Página de inicio de sesión en blanco tras el arranque. Revisa los registros del contenedor con docker compose logs stirling-pdf y asegúrate de que los directorios de volúmenes tengan los permisos correctos (chmod -R 755 ./stirling-data).

Opción de instalación 2: Integración con Traefik y Dockge

Esta configuración coloca Stirling PDF detrás de Traefik con HTTPS automático vía Let’s Encrypt. Dockge proporciona una interfaz web para gestionar el stack de compose.

Paso 1: Verificar la configuración de red

# Check for existing Traefik network
docker network ls | grep traefik-net

# Create if it doesn't exist
docker network create traefik-net

Paso 2: Configuración de Docker Compose

Crea un docker-compose.yml con etiquetas de Traefik:

services:
  stirling-pdf:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    volumes:
      - ./stirling-data/tessdata:/usr/share/tessdata
      - ./stirling-data/configs:/configs
      - ./stirling-data/logs:/logs
      - ./stirling-data/customFiles:/customFiles
      - ./stirling-data/pipeline:/pipeline
    environment:
      - SECURITY_ENABLELOGIN=true
      - SECURITY_INITIALLOGIN_USERNAME=admin
      - SECURITY_INITIALLOGIN_PASSWORD=ChangeMeNow123!
      - SYSTEM_DEFAULTLOCALE=en-US
      - SYSTEM_GOOGLEVISIBILITY=false
      - SYSTEM_MAXFILESIZE=500
      - SYSTEM_ROOTURIPATH=/
      - SPRING_SERVLET_MULTIPART_MAX_FILE_SIZE=2000MB
      - SPRING_SERVLET_MULTIPART_MAX_REQUEST_SIZE=2000MB
    networks:
      - traefik-net
    restart: unless-stopped
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.stirling-pdf.rule=Host(`pdf.yourdomain.com`)"
      - "traefik.http.routers.stirling-pdf.entrypoints=https"
      - "traefik.http.routers.stirling-pdf.tls=true"
      - "traefik.http.routers.stirling-pdf.tls.certresolver=letsencrypt"
      - "traefik.http.services.stirling-pdf.loadbalancer.server.port=8080"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/api/v1/info/status"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

networks:
  traefik-net:
    external: true

Nota: La personalización de la app (nombre, descripción, logo) ahora se configura dentro de la aplicación en Settings → UI, no mediante variables de entorno. Las antiguas variables UI_APPNAME y UI_HOMEDESCRIPTION se eliminaron en la V2.

Paso 3: Desplegar con Dockge

1. Accede a tu panel de Dockge (normalmente https://dockge.yourdomain.com)
2. Haz clic en “New Stack” y asígnale el nombre stirling-pdf
3. Pega la configuración de Docker Compose anterior
4. Actualiza pdf.yourdomain.com en las etiquetas de Traefik con tu dominio real
5. Haz clic en deploy y monitoriza los registros

Paso 4: Configuración de DNS

Apunta tu subdominio al servidor:

O usa un CNAME si tu dominio ya resuelve:

Paso 5: Verificar el acceso HTTPS

Una vez propagado el DNS:

• HTTPS: Navega a https://pdf.yourdomain.com
• Certificado SSL: Comprueba que el certificado de Let’s Encrypt sea válido (haz clic en el icono del candado en tu navegador)
• Documentación API: Visita https://pdf.yourdomain.com/swagger-ui.html

Opción de instalación 3: Despliegue con Dokploy

Dokploy proporciona una interfaz gráfica con gestión automatizada de certificados SSL. Funciona bien si prefieres hacer clic en lugar de escribir.

Paso 1: Configuración de la plataforma Dokploy

Si Dokploy aún no está instalado, sigue la guía de instalación y configuración de Dokploy.

Paso 2: Crear el proyecto Stirling PDF

1. Accede a tu panel de Dokploy
2. Haz clic en “New Project” y asígnale el nombre stirling-pdf
3. Selecciona “Compose” como tipo de aplicación. No uses la plantilla integrada de Stirling PDF, que puede estar fijada a una versión antigua de la V1

Formulario de creación de servicio de Dokploy mostrando la selección del tipo de aplicación compose

Paso 3: Configuración de variables de entorno

Establece estas variables de entorno en Dokploy:

Usa esto en la configuración compose de Dokploy:

environment:
  - SECURITY_ENABLELOGIN=${SECURITY_ENABLELOGIN}
  - SECURITY_INITIALLOGIN_USERNAME=${SECURITY_INITIALLOGIN_USERNAME}
  - SECURITY_INITIALLOGIN_PASSWORD=${SECURITY_INITIALLOGIN_PASSWORD}
  - SYSTEM_DEFAULTLOCALE=${SYSTEM_DEFAULTLOCALE}
  - SYSTEM_GOOGLEVISIBILITY=${SYSTEM_GOOGLEVISIBILITY}
  - SYSTEM_MAXFILESIZE=${SYSTEM_MAXFILESIZE}

Paso 4: Configuración de dominio y SSL

1. Navega a la sección “Domains” de tu proyecto Dokploy
2. Añade tu dominio: pdf.yourdomain.com
3. Activa la generación de certificados SSL/TLS
4. Activa la renovación automática de certificados
5. Configura la redirección de HTTP a HTTPS

Panel de configuración de dominio de Dokploy con el interruptor SSL activado

Paso 5: Desplegar y monitorizar

1. Haz clic en el botón “Deploy” en Dokploy
2. Monitoriza los registros de despliegue en busca de errores
3. Verifica que el indicador de salud muestre verde
4. Accede a tu instancia y prueba una operación PDF

Panel de despliegue de Dokploy mostrando los registros de compilación y el estado

Actualización de V1 a V2

Si ejecutas una instalación antigua de V1 (0.4x), esto es lo que debes saber antes de actualizar:

docker compose stop stirling-pdf
tar -czf stirling-v1-backup-$(date +%Y%m%d).tar.gz ./stirling-data/configs

Autenticación y gestión de usuarios

La V2 tiene el inicio de sesión activado por defecto.

Credenciales por defecto: admin / stirling. Cámbialas inmediatamente tras el primer inicio de sesión.

Predefinir credenciales iniciales (solo primer arranque, mediante variables de entorno):

environment:
  - SECURITY_INITIALLOGIN_USERNAME=myadmin
  - SECURITY_INITIALLOGIN_PASSWORD=YourSecurePassword123!

Solo se respetan en el primer arranque. Después, gestiona los usuarios desde la interfaz de administración.

Roles: Los usuarios administradores pueden gestionar todos los ajustes y usuarios. Los usuarios normales obtienen acceso a las operaciones PDF según la configuración.

Claves API: Cada usuario puede generar una clave API personal desde Account → Settings. Para automatización, define una clave API global:

environment:
  - SECURITY_CUSTOMGLOBALAPIKEY=your-long-random-key-here

Bloqueo de inicio de sesión: Por defecto, las cuentas se bloquean tras 5 intentos fallidos. Configúralo con:

environment:
  - SECURITY_LOGINATTEMPTCOUNT=5       # set -1 to disable lockout
  - SECURITY_LOGINRESETTIMEMINUTES=120  # lockout duration

SSO: OAuth2 está disponible en el nivel Server (99 $/mes). SAML2 requiere Enterprise. Para un operador en solitario en el nivel gratuito, quédate con cuentas locales.

Modo anónimo (sin inicio de sesión en absoluto):

environment:
  - SECURITY_ENABLELOGIN=false
  - DISABLE_ADDITIONAL_FEATURES=false

Para despliegues en producción, lee nuestra guía sobre gestión de secretos en Docker Compose para evitar poner contraseñas en texto plano.

Integración API y automatización

Stirling PDF expone una API REST. Con el inicio de sesión activado, todas las llamadas a la API requieren autenticación.

Autenticación de la API

Obtén tu clave API desde Account → Settings en la interfaz web, o define una clave global con SECURITY_CUSTOMGLOBALAPIKEY. Pásala como cabecera:

X-API-KEY: your-api-key

La documentación de la API está disponible en /swagger-ui.html (también accesible desde Settings → API Documentation). El registro Scalar en línea está en registry.scalar.com/@stirlingpdf.

Ejemplo: PDF a imágenes

curl -X POST "https://pdf.yourdomain.com/api/v1/convert/pdf-to-img" \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: multipart/form-data" \
  -F "[email protected]" \
  -F "imageFormat=PNG" \
  -F "singleOrMultiple=multiple"

Ejemplo: Pipeline (OCR + compresión en una llamada)

El sistema Pipeline/Automate permite encadenar varias operaciones en una única llamada a la API:

curl -X POST "https://pdf.yourdomain.com/api/v1/pipeline/handleData" \
  -H "X-API-KEY: your-api-key" \
  -F "[email protected]" \
  -F 'json={"name":"OCR-compress","pipeline":[
        {"operation":"/api/v1/misc/ocr-pdf","parameters":{"languages":["eng"],"ocrType":"skip-text"}},
        {"operation":"/api/v1/misc/compress-pdf","parameters":{"optimizeLevel":2}}]}' \
  --output result.pdf

Para procesamiento asíncrono, añade ?async=true a la URL del pipeline y consulta GET /api/v1/general/job/{id} para el estado.

Integración con flujos de n8n

Conecta Stirling PDF con n8n autoalojado para flujos de procesamiento de documentos:

1. Disparador: Recepción de un adjunto por correo o archivo depositado en una carpeta vigilada
2. Proceso: Una única llamada al pipeline para OCR + compresión + conversión
3. Almacenar: Guarda el resultado en tu sistema de gestión documental

Una única llamada al pipeline reemplaza lo que antes requería más de 5 nodos de API encadenados. Para uniones simples sin interfaz, también puedes usar pdfunite desde la línea de comandos de Linux.

Servidor MCP para agentes de IA

Stirling PDF incluye un servidor MCP (Model Context Protocol) integrado que expone las operaciones PDF como herramientas para agentes de IA. Es útil si estás construyendo flujos de trabajo de IA que necesitan procesar documentos.

Activa el servidor MCP en tu archivo compose:

environment:
  - MCP_ENABLED=true
  - MCP_AUTH_MODE=apikey
  - MCP_ALLOWEDOPERATIONS=stirling_pages,stirling_convert,stirling_misc,stirling_security

Grupos de herramientas disponibles: stirling_pages (unir/dividir/rotar), stirling_convert (conversiones de formato), stirling_misc (comprimir/OCR/reparar), stirling_security (contraseñas/firmas), stirling_upload, stirling_download.

Configuración de Claude Desktop: Añade esto a tu claude_desktop_config.json:

{
  "mcpServers": {
    "stirling-pdf": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://pdf.yourdomain.com/mcp",
        "--header",
        "X-API-KEY: your-api-key"
      ]
    }
  }
}

Los límites de petición y respuesta son de 10 MB por defecto. El servidor MCP no incluye un motor de IA. Expone las operaciones PDF como herramientas que los agentes de IA externos pueden invocar.

Buenas prácticas de seguridad y protección de datos

Stirling PDF ha tenido problemas de seguridad reales. Esto es lo que necesitas saber.

Protección SSRF

La conversión de URL a PDF está desactivada por defecto (system.enableUrlToPDF: false) por el riesgo de SSRF. Si la activas, la protección SSRF está activada por defecto en nivel MEDIUM (bloquea RFC1918, localhost, link-local y endpoints de metadatos de la nube). Establécela en MAX para el modo de solo lista de permitidos:

# In settings.yml
system:
  enableUrlToPDF: true
  urlToPdfProtection: MAX
  allowedDomains:
    - "trusted-domain.com"

Avisos de seguridad

Stirling PDF ha tenido varios avisos de seguridad. Los principales:

Seguridad de red y acceso

• Bloquea la indexación en buscadores: SYSTEM_GOOGLEVISIBILITY=false (ya configurado en los ejemplos de compose anteriores)
• Desactiva endpoints sin usar: Configura endpoints.toRemove en settings.yml para deshabilitar endpoints de la API que no utilices
• Solo HTTPS: Ejecuta siempre detrás de un proxy inverso con TLS. Nunca expongas el puerto 8080 directamente a internet
• Limitación de tasa: Bloqueo por intentos de inicio de sesión más integración con fail2ban para protección contra fuerza bruta

Almacenamiento y copias de seguridad

Qué respaldar

Los datos críticos residen en estas ubicaciones (todas dentro de tus volúmenes montados):

Procedimiento de copia de seguridad

# Stop the container for a consistent snapshot
docker compose stop stirling-pdf

# Create a compressed backup
tar -czf stirling-backup-$(date +%Y%m%d-%H%M%S).tar.gz \
  -C ./stirling-data configs customFiles tessdata pipeline

# Restart
docker compose start stirling-pdf

Procedimiento de restauración

# Stop the container
docker compose stop stirling-pdf

# Extract backup (overwrites current data)
tar -xzf stirling-backup-YYYYMMDD-HHMMSS.tar.gz -C ./stirling-data

# Verify critical files exist
ls -la ./stirling-data/configs/stirling-pdf-DB-*.mv.db
ls -la ./stirling-data/configs/settings.yml

# Restart
docker compose start stirling-pdf

Almacenamiento S3 (opcional)

La V2.12+ admite almacenamiento compatible con S3 para subidas y artefactos. Es útil para configuraciones multiservidor o cuando quieres almacenamiento duradero separado del host del contenedor. Se configura en settings.yml en la sección de almacenamiento. Los niveles Server y Enterprise también admiten PostgreSQL externo en lugar de la base de datos H2 embebida.

Rendimiento y gestión de recursos

Guía de dimensionamiento

La V2.12.0 introdujo JPDFium para las operaciones de unir y dividir, usando hasta un 99 % menos de memoria que el motor anterior. La V2.14.3 corrigió fallos al procesar PDFs de más de 2 GB.

Límites de recursos de Docker

Establece límites estrictos para evitar que un proceso desbocado tumbe tu servidor:

services:
  stirling-pdf:
    # ... other configuration
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 4G
        reservations:
          cpus: '1.0'
          memory: 2G

Para ajustar la memoria, define JAVA_TOOL_OPTIONS=-Xmx2g para limitar el heap de la JVM.

Monitorización y comprobaciones de salud

El endpoint de salud /api/v1/info/status siempre es accesible sin autenticación. Úsalo con Uptime Kuma, Beszel o cualquier herramienta de monitorización que admita comprobaciones de salud HTTP.

Las estadísticas de uso están disponibles en /api/v1/info/requests/all (peticiones totales) y /api/v1/info/requests/unique (peticiones únicas).

Solución de problemas comunes

environment:
  - SERVER_JETTY_MAX_HTTP_REQUEST_HEADER_SIZE=16384

Mantenimiento y actualizaciones

Procedimiento de actualización

cd ~/stirling-pdf

# Pull the latest image
docker compose pull

# Recreate the container
docker compose up -d

# Clean up old images
docker image prune -f

Fijar la versión: En producción, considera fijar una etiqueta específica (p. ej., docker.stirlingpdf.com/stirlingtools/stirling-pdf:v2.14.3) en lugar de :latest. Esto evita roturas sorpresa por actualizaciones automáticas. Cuando estés listo para actualizar, cambia la etiqueta y ejecuta docker compose pull && docker compose up -d.

Haz copia de seguridad antes de actualizaciones importantes. La propia versión v2.12.0 recomendaba respaldar antes de actualizar. Las versiones se publican de 2 a 4 veces por semana e incluyen correcciones de seguridad — suscríbete al feed de versiones de GitHub para estar al tanto.

Para actualizaciones automatizadas de contenedores, considera autoactualizar contenedores Docker con Tugtainer.

Calendario de mantenimiento

Conclusión

Autoalojar Stirling PDF te da una plataforma de procesamiento de PDF privada y capaz que se ejecuta en tu propia infraestructura. La reescritura de la V2 trajo un frontend moderno en React, procesamiento PDFium de bajo consumo de memoria, un servidor MCP integrado para la integración con agentes de IA y Automate/Pipelines para encadenar operaciones.

Empieza con la Opción 1 (Docker Compose independiente) para estar en marcha en 5 minutos. Añade Traefik cuando necesites HTTPS. Usa Dokploy si quieres una interfaz gráfica. Las aplicaciones de escritorio son un extra para procesamiento local en tus propias máquinas.

Explora nuestras guías sobre orquestación de contenedores Docker con Dockge, configuración de proxy inverso Traefik y gestión de la plataforma Dokploy.