--- title: "Cómo Autoalojar Stirling PDF (Docker, Traefik, Dokploy)" description: "Autoaloja Stirling PDF con Docker para unir, dividir, convertir y proteger PDFs de forma privada. Guía paso a paso con Traefik, Dokploy, API y configuración MCP." date: 2025-07-30 categories: ["self-hosting"] tags: ["self-hosted","docker","stirling-pdf"] --- import Button from "@components/widgets/Button.astro"; import Notice from "@components/widgets/Notice.astro"; import ListCheck from "@components/widgets/ListCheck.astro"; import Accordion from "@components/widgets/Accordion.astro"; 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](https://www.bitdoze.com/es/contenedores-docker-servidor-casa/). ## ¿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 - Gestión de documentos: une, divide, rota, reorganiza y compara páginas PDF - Conversión de formatos: PDF a/desde imágenes, Word, Excel, HTML, Markdown y más - Operaciones de seguridad: añadir/eliminar contraseñas, firmas digitales, cifrado, tachado de datos - Compresión y optimización: reduce el tamaño de los archivos manteniendo la calidad - Integración OCR: extrae texto de documentos escaneados con Tesseract - Gestión de metadatos: limpia, edita o elimina los metadatos del documento - Procesamiento por lotes: maneja varios documentos simultáneamente desde la interfaz Automate/Pipeline - Acceso API: endpoints RESTful para flujos de automatización y scripting - Servidor MCP: expone las operaciones PDF como herramientas para agentes de IA (Claude Desktop, etc.) - Compartición de archivos y firma en grupo: comparte documentos para firma colaborativa (alfa desde v2.9.0) - Aplicaciones de escritorio: clientes nativos de Windows, macOS y Linux para procesamiento local ### Cómo funciona Stirling PDF | Componente | Función | Detalles | |-----------|----------|---------| | Interfaz web | GUI en el navegador | Frontend React, más de 38 idiomas, modo oscuro | | Motor de procesamiento | Núcleo PDF basado en Java | JDK 25, JPDFium para unir/dividir con bajo consumo de memoria | | Motor OCR | Integración con Tesseract | Paquetes de idioma vía directorio tessdata | | Conversiones de Office | LibreOffice | DOCX, XLSX, PPTX a PDF y viceversa | | Capa API | Endpoints RESTful | Swagger UI en `/swagger-ui.html` | | Servidor MCP | Integración con agentes de IA | `POST /mcp`, desactivado por defecto | | Almacenamiento | Temporal + persistente | BD H2, settings.yml, backend S3 opcional | Stirling PDF es un proyecto de código abierto. Consulta la documentación y contribuye en el [repositorio de GitHub](https://github.com/Stirling-Tools/Stirling-PDF) y el [sitio web del proyecto](https://stirling.com). La documentación completa está en [docs.stirlingpdf.com](https://docs.stirlingpdf.com/). ## Licencias: gratuita, servidor y empresarial Stirling PDF pasó a un modelo open-core. El desglose para quienes se autoalojan: **Gratuita (autoalojada):** Hasta 5 usuarios, las más de 60 operaciones, sin créditos ni funciones bloqueadas. Esto es lo que obtienes por defecto al desplegar con Docker. Realmente gratuita e ilimitada en operaciones. **Server (99 $/mes o 999 $/año):** 100 usuarios (ampliables en bloques de 100), SSO OAuth2, PostgreSQL externo, tickets de soporte, integración con Google Drive. **Enterprise (precio personalizado):** SAML2, activación de certificados en entornos aislados (air-gapped), métricas Prometheus, registros de auditoría, SLAs. Activación: Settings → Plan (Stripe integrado en la app) o `settings.yml` → `premium.key`. 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: **Mínimo:** 2 núcleos de CPU, 2 GB de RAM, 10 GB de disco **Recomendado:** 4+ núcleos de CPU, 4 GB+ de RAM, almacenamiento SSD **Tamaño de la imagen:** La etiqueta `latest` ocupa aproximadamente 1 GB comprimida. Tenlo en cuenta para la descarga. Las conversiones pesadas (LibreOffice) y las operaciones OCR necesitan más RAM. La variante `latest-ultra-lite` está disponible para Raspberry Pi y VPS de gama baja, pero carece de compresión, OCR y conversiones de ofimática. **Variantes de imagen:** | Variante | Etiqueta | Ideal para | Funciones ausentes | |---------|-----|----------|-----------------| | Estándar | `:latest` | La mayoría de despliegues | Ninguna | | Fat | `:latest-fat` | Conversiones de alta fidelidad, fuentes extra | Mayor tamaño de imagen | | Ultra Lite | `:latest-ultra-lite` | Raspberry Pi, VPS de gama baja | Sin compresión, OCR, conversiones de ofimática, reparación, PDF/A | **Requisitos de infraestructura:** - **Servidor**: Un VPS o servidor dedicado. [Hetzner VPS](https://go.bitdoze.com/hetzner) o [Hostinger VPS](https://go.bitdoze.com/hostinger-vps) funcionan bien para esto. Para instalación local, consulta [mini PCs para servidores domésticos](https://www.bitdoze.com/best-mini-pc-home-server/). - **Docker Engine**: Última versión estable con Docker Compose v2 - **Proxy inverso** (para HTTPS): Configura un [proxy inverso Traefik en Docker](https://www.bitdoze.com/traefik-proxy-docker/) o usa Caddy. Para certificados SSL, sigue la [guía de certificado wildcard de Traefik](https://www.bitdoze.com/traefik-wildcard-certificate/). - **Gestión de contenedores** (opcional): [Dockge](https://www.bitdoze.com/es/instalar-dockge/) para gestionar stacks o [Dokploy](https://www.bitdoze.com/dokploy-install/) 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](/es/subidas-precios-vps/)._ ## 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 ```bash mkdir -p ~/stirling-pdf && cd ~/stirling-pdf ``` ### Paso 2: Configurar Docker Compose Crea un archivo `docker-compose.yml`: ```yaml 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 ``` La V2 incluye el inicio de sesión activado por defecto. La cuenta por defecto es `admin` / `stirling`. Cambia la contraseña inmediatamente después del primer inicio de sesión. Algunas compilaciones fuerzan un cambio de contraseña en el primer inicio. Puedes predefinir las credenciales iniciales con `SECURITY_INITIALLOGIN_USERNAME` y `SECURITY_INITIALLOGIN_PASSWORD` (solo se respetan en el primer arranque). 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 ```bash mkdir -p stirling-data/{tessdata,configs,logs,customFiles,pipeline} docker compose up -d ``` Observa los registros para confirmar el arranque: ```bash 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: ```bash # 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: ```bash 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` Tu instancia de Stirling PDF está en funcionamiento. Inicia sesión con tus credenciales (o `admin`/`stirling` si no las predefiniste) y cambia la contraseña inmediatamente. **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. Esta configuración requiere una instalación funcional de Traefik y Dockge. Sigue la [guía de certificado wildcard de Traefik](https://www.bitdoze.com/traefik-wildcard-certificate/) para la configuración SSL. ### Paso 1: Verificar la configuración de red ```bash # 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: ```yaml 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: | Tipo de registro | Nombre | Valor | TTL | |-------------|------|-------|-----| | A | pdf | ip-de-tu-servidor | 300 | O usa un CNAME si tu dominio ya resuelve: | Tipo de registro | Nombre | Valor | TTL | |-------------|------|-------|-----| | CNAME | pdf | yourdomain.com | 300 | Los cambios de DNS pueden tardar entre 5 y 15 minutos en propagarse. Espera antes de verificar el acceso HTTPS. ### 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](https://www.bitdoze.com/dokploy-install/). ### 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](@assets/images/25/07/dokploy-createservice.png) ### Paso 3: Configuración de variables de entorno Establece estas variables de entorno en Dokploy: | Variable | Valor | Descripción | |----------|-------|-------------| | `SECURITY_ENABLELOGIN` | `true` | Activa el inicio de sesión (por defecto en V2) | | `SECURITY_INITIALLOGIN_USERNAME` | `admin` | Nombre de usuario admin inicial (solo primer arranque) | | `SECURITY_INITIALLOGIN_PASSWORD` | `ChangeMeNow123!` | Contraseña inicial (solo primer arranque) | | `SYSTEM_DEFAULTLOCALE` | `en-US` | Idioma de la interfaz | | `SYSTEM_GOOGLEVISIBILITY` | `false` | Bloquea la indexación en buscadores | | `SYSTEM_MAXFILESIZE` | `500` | Tamaño máximo de archivo en MB | Usa esto en la configuración compose de Dokploy: ```yaml 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](@assets/images/25/07/dokploy-domain.png) ### 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](@assets/images/25/07/dokploy-deploy.png)