Cómo instalar Stirling PDF con Docker paso a paso

Instalar Stirling PDF con Docker permite convertir la aplicación en un servidor privado para gestionar documentos PDF. Una vez desplegado, podrás acceder desde cualquier ordenador, móvil o tableta de la red mediante el navegador, sin instalar el programa en cada dispositivo.

Los archivos se envían al servidor configurado por ti y no a los servidores de Stirling PDF. Esto proporciona más control sobre los documentos, aunque la privacidad final también depende de dónde se encuentre el servidor, quién pueda acceder y cómo se proteja la conexión.

Si solamente vas a utilizar la herramienta desde un único PC, la aplicación nativa puede resultar más sencilla. En ese caso, consulta cómo instalar Stirling PDF en Windows sin configurar Docker ni publicar un servicio de red.

Qué imagen de Stirling PDF debes elegir

Stirling PDF publica tres variantes de su imagen. La elección influye en las funciones disponibles, el espacio ocupado y los recursos necesarios.

Versión	Etiqueta	Uso recomendado
Standard	latest	La mayoría de los usuarios y servidores domésticos
Fat	latest-fat	Máxima compatibilidad, fuentes y herramientas adicionales
Ultra-Lite	latest-ultra-lite	Raspberry Pi, VPS pequeños y operaciones básicas

La imagen latest es la recomendada cuando no tienes requisitos especiales. Incluye las funciones habituales de gestión, conversión, OCR y seguridad manteniendo un tamaño razonable.

La variante latest-fat incorpora más fuentes y herramientas opcionales, por lo que puede mejorar la compatibilidad en determinadas conversiones. A cambio, necesita más almacenamiento.

latest-ultra-lite reduce el tamaño y el consumo para dispositivos limitados, pero prescinde de algunas funciones. Resulta adecuada para fusionar, dividir, rotar o reorganizar documentos en equipos modestos.

Una vez instalado el servidor podrás unir varios PDF con Stirling PDF, eliminar páginas, reorganizar documentos o convertir varias imágenes en un único PDF.

Requisitos para instalar Stirling PDF con Docker

Para un despliegue básico necesitas:

• Docker Engine 20.10 o posterior.
• Docker Compose instalado.
• Un mínimo de 2 GB de memoria RAM.
• Al menos 5 GB de almacenamiento para una prueba básica.
• Una carpeta donde guardar la configuración persistente.
• Acceso a una terminal o a una interfaz compatible con Compose.

Para un servidor utilizado habitualmente se recomiendan 2 núcleos de CPU, 4 GB de RAM y 10 GB libres. Las conversiones, el renderizado y el OCR pueden necesitar varias veces el tamaño del documento en memoria.

Comprueba la instalación:

docker --version
docker compose version

En sistemas actuales es preferible utilizar docker compose, con un espacio. Algunas interfaces y versiones antiguas continúan mostrando docker-compose, pero ambos comandos no siempre están disponibles simultáneamente.

Instalación rápida mediante docker run

Para probar Stirling PDF sin crear todavía un archivo de Compose, ejecuta:

docker run -d \
  --name stirling-pdf \
  -p 8080:8080 \
  -v ./stirling-data:/configs \
  docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest

Después abre:

http://localhost:8080

Si Docker se ejecuta en otro equipo, sustituye localhost por su dirección IP:

http://192.168.1.50:8080

El volumen ./stirling-data:/configs conserva los ajustes y la base de datos cuando el contenedor se elimina o actualiza.

Esta modalidad sirve para una prueba rápida. Para una instalación permanente resulta más cómodo utilizar Docker Compose, ya que deja documentados los puertos, volúmenes, variables y políticas de reinicio.

Cómo preparar las carpetas persistentes

Crea una carpeta para el proyecto y varios directorios persistentes:

mkdir -p ~/stirling-pdf/stirling-data/{configs,logs,pipeline,tessdata}
cd ~/stirling-pdf

Cada directorio cumple una función diferente:

• configs: ajustes y base de datos interna.
• logs: registros de funcionamiento y errores.
• pipeline: configuraciones para procesamientos automatizados.
• tessdata: modelos lingüísticos utilizados por Tesseract.

También puedes crear un volumen para /customFiles si necesitas fuentes, temas, firmas u otros archivos personalizados.

No es necesario configurar PUID y PGID en todas las instalaciones. Algunas plantillas comunitarias para NAS o Unraid utilizan esas variables, pero la configuración oficial básica se apoya en los permisos de las carpetas montadas.

Cómo instalar Stirling PDF con Docker Compose

Dentro de ~/stirling-pdf, crea un archivo llamado docker-compose.yml con este contenido:

services:
  stirling-pdf:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    ports:
      - "8080:8080"
    volumes:
      - ./stirling-data/configs:/configs
      - ./stirling-data/logs:/logs
      - ./stirling-data/pipeline:/pipeline
      - ./stirling-data/tessdata:/usr/share/tessdata
    environment:
      SECURITY_ENABLELOGIN: "true"
      SECURITY_INITIALLOGIN_USERNAME: "admin"
      SECURITY_INITIALLOGIN_PASSWORD: "${STIRLING_ADMIN_PASSWORD}"
      SYSTEM_DEFAULTLOCALE: "es-ES"
    restart: unless-stopped

Crea también un archivo .env en la misma carpeta:

STIRLING_ADMIN_PASSWORD=INTRODUCE_UNA_CONTRASEÑA_SEGURA

Protege el archivo para que solamente tu usuario pueda leerlo:

chmod 600 .env

Después inicia el servicio:

docker compose up -d

Comprueba su estado:

docker compose ps

El contenedor debe aparecer como iniciado. Durante el primer arranque puede tardar unos segundos en preparar la base de datos y los componentes internos.

Cómo configurar el idioma y la autenticación

Las imágenes Docker actuales tienen el inicio de sesión activado por defecto. Si no defines credenciales iniciales, se crea una cuenta con:

• Usuario: admin
• Contraseña: stirling

Debes cambiar esta contraseña inmediatamente. La configuración anterior evita utilizarla estableciendo una clave propia desde el primer despliegue.

Las variables SECURITY_INITIALLOGIN_USERNAME y SECURITY_INITIALLOGIN_PASSWORD se utilizan al crear la cuenta inicial. No sirven para cambiar posteriormente la contraseña de un usuario ya existente; ese cambio debe realizarse desde la interfaz.

Si el servidor está completamente aislado y quieres utilizarlo sin autenticación, puedes indicar:

SECURITY_ENABLELOGIN: "false"

No desactives la autenticación si otros usuarios pueden alcanzar el puerto, si utilizas una red compartida o si vas a publicar el servicio en Internet.

Para utilizar español como idioma predeterminado, la variable actual es:

SYSTEM_DEFAULTLOCALE: "es-ES"

Si no se establece, Stirling PDF intenta detectar el idioma del navegador. Para limitar los idiomas disponibles en el selector puedes utilizar UI_LANGUAGES, cuyos códigos utilizan guion bajo:

UI_LANGUAGES: "es_ES,en_US"

Cómo añadir OCR en español

Stirling PDF utiliza Tesseract para reconocer texto dentro de documentos escaneados. El OCR extrae texto, pero no reconstruye automáticamente tablas, fórmulas ni estructuras complejas.

Para reconocer documentos en español, descarga el archivo spa.traineddata desde los repositorios oficiales de Tesseract y guárdalo en:

~/stirling-pdf/stirling-data/tessdata

La carpeta está conectada con /usr/share/tessdata dentro del contenedor mediante el archivo de Compose.

No elimines eng.traineddata. Stirling PDF necesita conservar el modelo inglés aunque añadas otros idiomas.

Puedes escoger entre:

• tessdata_fast: archivos más pequeños y rápidos, con menor precisión potencial.
• tessdata: modelos más pesados que pueden ofrecer mejores resultados.

Después de añadir el archivo, reinicia el contenedor:

docker compose restart stirling-pdf

El OCR permite convertir un escaneo en un PDF buscable. Si después necesitas modificar el contenido, puedes convertir el PDF a Word con Stirling PDF, teniendo en cuenta que la fidelidad dependerá del diseño original.

Cómo acceder desde otros dispositivos de la red

Busca la dirección IP del equipo que ejecuta Docker y abre desde otro dispositivo:

http://DIRECCION_IP:8080

Por ejemplo:

http://192.168.1.50:8080

Si la página no carga, comprueba que el cortafuegos permita conexiones TCP al puerto 8080 desde la red local.

No necesitas publicar el puerto en el router para utilizarlo dentro de casa u oficina. Mantenerlo limitado a la LAN reduce la superficie de ataque.

Desde la interfaz podrás realizar operaciones como eliminar páginas en blanco y editar documentos, añadir anotaciones o añadir una marca de agua a un PDF.

Cómo acceder remotamente de forma segura

No expongas directamente el puerto 8080 a Internet mediante una redirección del router. La conexión utilizaría HTTP y podría quedar accesible para rastreadores o atacantes.

Las alternativas más seguras son:

• Acceder mediante una VPN privada como WireGuard o Tailscale.
• Utilizar un proxy inverso con dominio y certificado HTTPS.
• Configurar un túnel autenticado como Cloudflare Tunnel.

Nginx, Caddy o Traefik pueden actuar como proxy inverso y enviar las peticiones HTTPS al contenedor mediante http://localhost:8080. El certificado puede gestionarse con Let’s Encrypt o con el proveedor del dominio.

La autenticación de Stirling PDF debe permanecer activada incluso cuando el proxy ya proteja la conexión. El cifrado HTTPS protege el transporte, mientras que el inicio de sesión controla quién puede utilizar la aplicación.

Cómo instalar Stirling PDF en Raspberry Pi o un NAS

En una Raspberry Pi con recursos limitados puedes cambiar la imagen por:

docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest-ultra-lite

Las operaciones sencillas deberían funcionar correctamente, pero el OCR, las conversiones de Office y el procesamiento de documentos grandes pueden ser lentos o superar la memoria disponible.

En Synology, QNAP y otros NAS compatibles puedes desplegar el mismo archivo mediante Docker Compose, Container Manager o Portainer. En Portainer, abre Stacks > Add stack, pega la configuración y adapta las rutas para que apunten a carpetas compartidas persistentes.

Comprueba los permisos de escritura sobre configs, logs, pipeline y tessdata. Utiliza PUID y PGID solamente cuando la plantilla concreta del NAS los admita.

Cómo ajustar el rendimiento

Una instalación para un equipo pequeño puede comenzar con 2 núcleos, 4 GB de RAM y 10 GB libres. Los documentos con muchas páginas, fuentes incrustadas o gráficos vectoriales pueden expandirse considerablemente durante el procesamiento.

Las operaciones más exigentes suelen ser:

• OCR mediante Tesseract u OCRmyPDF.
• Conversión de documentos con LibreOffice.
• Conversión de PDF a imágenes.
• Compresión y reparación de archivos grandes.

No aumentes los límites de procesos simultáneos sin vigilar la memoria. En servidores modestos resulta preferible procesar los documentos en cola antes que provocar un error por falta de RAM.

Si el servidor trabaja para varios usuarios, consulta el consumo mediante:

docker stats stirling-pdf

Cómo actualizar Stirling PDF sin perder datos

Antes de actualizar, crea una copia de las carpetas persistentes, el archivo de Compose y el archivo .env:

tar -czf stirling-backup.tar.gz \
  stirling-data docker-compose.yml .env

Guarda la copia en otro dispositivo o sistema de almacenamiento. El archivo .env contiene la contraseña inicial y debe permanecer protegido.

Después actualiza la imagen:

docker compose down
docker compose pull
docker compose up -d

Los datos permanecen en las carpetas montadas. En un servidor importante conviene sustituir latest por una versión concreta para controlar cuándo se aplican los cambios.

Errores frecuentes al instalar Stirling PDF con Docker

Docker no encuentra la imagen frooodle/s-pdf

Las guías antiguas utilizaban frooodle/s-pdf. Sustituye esa referencia por:

docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest

Si el registro principal no responde, también puedes utilizar:

ghcr.io/stirling-tools/stirling-pdf:latest

El puerto 8080 ya está ocupado

Cambia solamente el puerto del equipo anfitrión:

ports:
  - "9000:8080"

Después accede mediante http://localhost:9000.

El contenedor se reinicia continuamente

Consulta los registros:

docker logs stirling-pdf

Comprueba el espacio disponible, la memoria y los permisos de escritura sobre los volúmenes. En equipos limitados prueba la imagen latest-ultra-lite.

Los ajustes desaparecen después de actualizar

El volumen /configs no está montado correctamente o apunta a una carpeta diferente. Comprueba la ruta dentro de docker-compose.yml y que el usuario del contenedor pueda escribir en ella.

La interfaz no aparece en español

Utiliza SYSTEM_DEFAULTLOCALE=es-ES. La antigua variable LANGS=es_ES no establece el idioma predeterminado en la configuración actual.

El OCR no muestra español

Comprueba que spa.traineddata exista dentro de la carpeta montada y que el volumen apunte a /usr/share/tessdata. Conserva también eng.traineddata.

No puedo iniciar sesión

En una instalación nueva sin credenciales personalizadas, prueba admin y stirling y cambia inmediatamente la contraseña. Si la base de datos ya existía, las variables de inicio inicial no sustituyen las credenciales guardadas.

Permission denied al utilizar un volumen

Crea las carpetas antes de levantar el contenedor y revisa su propietario y permisos. No apliques permisos de escritura globales indiscriminadamente ni configures 777 como solución permanente.

La aplicación funciona localmente, pero no desde otro equipo

Comprueba que estás usando la IP del servidor, que el puerto está publicado y que el cortafuegos permite conexiones desde la red local. localhost siempre se refiere al dispositivo desde el que abres el navegador.

El servidor se queda sin memoria con archivos grandes

Reduce las operaciones simultáneas, utiliza la variante Ultra-Lite si no necesitas herramientas avanzadas o amplía la RAM. El OCR y el renderizado pueden consumir varias veces el tamaño del archivo original.

Instalar Stirling PDF con Docker permite ofrecer una plataforma centralizada de gestión documental a todos los dispositivos de una red. La imagen estándar resulta adecuada para la mayoría, mientras que las variantes Fat y Ultra-Lite permiten priorizar compatibilidad o consumo reducido.

La parte crítica consiste en montar correctamente los volúmenes, mantener la autenticación, configurar OCR solo cuando sea necesario y proteger cualquier acceso remoto mediante VPN o HTTPS. También debes respaldar /configs antes de actualizar, ya que contiene los ajustes y la base de datos de la instalación.