Cómo actualizar Stirling-PDF a 3.0 con Docker sin perder datos

Stirling-PDF 3.0.0 salió el 24 de septiembre de 2026 y en Docker se actualiza cambiando la etiqueta de la imagen, sin pasos de migración a mano. Si seguiste la guía para instalar Stirling-PDF con Docker, tienes una 2.14 fijada, y en mi prueba la 3.0 conservó usuarios, ajustes, claves de API y carpetas vigiladas. Lo que cambia de verdad está en la letra pequeña: la API y las automatizaciones gastan ahora un cupo de 1000 PDF al mes, y la carpeta de archivos del servidor vive en un directorio que tu docker-compose.yml no monta. Esta guía recorre la copia de seguridad, el cambio de etiqueta, lo que comprobé después y la vuelta a la 2.14.3, con los errores reales que vi. También está en inglés.

Puntos clave

• La 3.0.0 es la última imagen de Docker: la 3.0.1 del 26 de septiembre solo corrige la aplicación de escritorio de Windows y no tiene etiqueta en Docker Hub ni en ghcr.io.
• Desde la 2.14.3, el salto fue cambiar la etiqueta y ejecutar docker compose up -d: el login, los 5 usuarios, la clave de API y la carpeta vigilada siguieron funcionando.
• La 3.0 cuenta 1 unidad por cada llamada a la API con clave y por cada archivo de una carpeta procesada; tras 1000 unidades, la API responde 402 con FREE_TIER_EXHAUSTED, y la carpeta vigilada antigua también se para.
• El editor web queda fuera del límite: la misma operación con la sesión del navegador devolvió 200 con el cupo ya agotado.
• Hay que guardar un archivo nuevo, configs/credential-encryption.key, y montar /storage si activas el almacenamiento en el servidor.
• Volver a la 2.14.3 restaurando la copia funcionó a la primera, con usuarios y clave de API intactos.

¿Qué cambia en Stirling-PDF 3.0 si lo tienes en Docker?

La 3.0 es sobre todo una versión de funciones: las notas de Stirling-PDF 3.0.0^[1] la resumen como "PDF Processor, Brand new text editor, Free OAuth and tons of new features". Para quien la ejecuta en Docker, estas son las diferencias que tocan tu despliegue:

• Contador de automatización: la API, el Processor y las funciones de IA consumen un cupo mensual gratuito; el editor web queda fuera
• STIRLING_JVM_PROFILE: la variable que elegía el perfil de memoria de Java queda obsoleta, y la imagen usa un único _JVM_OPTS
• Archivo credential-encryption.key: aparece en /configs en el primer arranque y cifra los secretos de integraciones
• Almacenamiento en el servidor: la biblioteca de archivos y "Procesar una carpeta" guardan en /storage, un directorio que la configuración de la 2.x no monta
• Carpetas vigiladas: la interfaz para crearlas desaparece (PR 8170), pero el motor sigue procesando /pipeline/watchedFolders
• LibreOffice aislado: las conversiones de ofimática se ejecutan dentro de un sandbox con Landlock y seccomp

La imagen arm64 pasa de 1,02 GB comprimida en la 2.14.3 a 1,10 GB en la 3.0.0, según el registro de etiquetas de Docker Hub^[2]. El puerto sigue siendo el 8080 y el nombre de la imagen no cambia.

La documentación oficial aún no explica el paso de la 2.x a la 3.0. La guía de migración de Stirling PDF^[3] solo cubre el salto de la 1.x a la 2.x. Lo que sigue sale de haber hecho la actualización y de leer el código de arranque de las dos imágenes.

¿Cuánto cuesta la automatización en Stirling-PDF 3.0?

El cambio que más afecta a una instalación con integraciones es el cupo gratuito. Las notas de la versión lo dicen así: "Automation now includes 1,000 PDFs per month free. This allowance applies to automated processing through Processor, API, and AI features." Vincular el servidor a stirling.com suma otros 500 PDF al mes, y el uso normal del editor sigue siendo gratuito e ilimitado.

Medí el contador con el endpoint que usa la propia interfaz, /api/v1/account-link/free-tier. El periodo no es el mes natural: empieza en el primer arranque de la 3.0 y dura un mes. Esta tabla recoge lo que gastó cada operación en mi prueba:

Para ver qué pasa al agotarlo, lancé 991 llamadas a la API de rotación con un PDF de una página. La llamada que hacía la unidad 1001 recibió esto:

$ curl -s -X POST http://127.0.0.1:8080/api/v1/general/rotate-pdf \
    -H "X-API-KEY: tu_clave_de_api" \
    -F fileInput=@una_pagina.pdf -F angle=90
{"error":"ACCOUNT_LINK_REQUIRED","reason":"FREE_TIER_EXHAUSTED"}

El código HTTP es 402. La misma rotación con la sesión del navegador siguió devolviendo 200, y la carpeta vigilada antigua dejó de procesar: registró el mismo 402 al llamar a /api/v1/misc/ocr-pdf y dejó el archivo en processing/. Si un script, un n8n o cualquier otra integración llama a tu Stirling-PDF con clave de API, calcula su volumen mensual antes de actualizar.

El plan gratuito ya limitaba los usuarios en la 2.14.3, y la 3.0 mantiene la cifra: el sexto usuario recibió en ambas versiones "Maximum number of users reached. Allowed: 5". Según la página de planes de pago de Stirling PDF^[4], el plan Team cuesta 99 dólares al mes o 999 al año e incluye 100 usuarios.

Cómo he probado la actualización

Probé la actualización el 27 de septiembre de 2026 en un equipo aarch64 de 18 núcleos y 47 GiB con Docker 29.5.2. Partí del docker-compose.yml de la guía de instalación, con sus cuatro volúmenes, el login activado, SYSTEM_DEFAULTLOCALE=es-ES y STIRLING_JVM_PROFILE=performance. Ejecuté todo con un nombre de proyecto propio y el puerto publicado en 127.0.0.1:22780. Sobre la 2.14.3 creé este estado:

• 4 usuarios además de admin, el máximo del plan gratuito
• Una clave de API para admin
• Tres ajustes cambiados desde la API de administración: nombre de la aplicación, límite de subida de 200 MB y analítica desactivada
• Una carpeta vigilada facturas con un JSON que aplica OCR en español, que convirtió 5 facturas escaneadas de 2 páginas en PDF con texto
• Una automatización "Comprimir y OCR facturas" guardada en el navegador

No publico tiempos de proceso: otros trabajos compartían la máquina y la carga media osciló entre 10 y 43 durante toda la sesión. Docker Hub respondió 429 Too Many Requests al descargar, así que usé las mismas imágenes desde ghcr.io; la 3.0.0 tiene el mismo digest sha256:66b6edb8… en los dos registros.

La copia de seguridad antes de cambiar la etiqueta

La copia que me permitió volver fue un tar de la carpeta data y del docker-compose.yml con el contenedor parado. El contenedor escribe como root en el directorio de tessdata, así que empaqueté desde un contenedor para conservar propietarios y permisos:

docker compose stop
docker run --rm -v "$PWD":/stack -w /stack alpine \
  tar czf /stack/stirling-backup-2.14.3.tar.gz data compose.yaml

En mi instalación de prueba el archivo ocupó 1,4 MB. Tres cosas quedan fuera de esa copia y conviene saberlo:

• Automatizaciones de "Automatizar": viven en la base de datos IndexedDB StirlingPDF_Automations de cada navegador, no en el servidor. Exporta las que te importen desde el propio diálogo
• credential-encryption.key: todavía no existe; la 3.0 lo crea en el primer arranque, y a partir de ahí va en todas tus copias
• Una base de datos externa: si usas PostgreSQL, haz su volcado aparte; mi prueba usó la H2 integrada, que vive en /configs

La 3.0 también hace su propio volcado SQL al arrancar, en configs/backup/db/. En mi caso dejó un backup_202609271142.sql de 50 KB, pero es un volcado hecho por la versión nueva y no sustituye a la copia en frío.

Actualizar Stirling-PDF a 3.0 paso a paso

La actualización son tres cambios en el docker-compose.yml y un docker compose up -d. Este es el archivo que terminé usando con la 3.0.0:

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:3.0.0
    container_name: stirling-pdf
    restart: unless-stopped
    mem_limit: 4g
    ports:
      - "8080:8080"
    volumes:
      - ./data/tessdata:/usr/share/tessdata
      - ./data/configs:/configs
      - ./data/logs:/logs
      - ./data/pipeline:/pipeline
      - ./data/storage:/storage
    environment:
      SECURITY_ENABLELOGIN: "true"
      SYSTEM_DEFAULTLOCALE: "es-ES"

Respecto al de la 2.14, cambian tres líneas y cada una tiene su motivo:

1. La etiqueta pasa a 3.0.0. Fija la versión en lugar de latest, que ya apunta a la 3.0.0 y saltará sola a la siguiente.
2. Se añade ./data/storage:/storage. La imagen no declara ese directorio como volumen, así que sin esta línea los archivos de la biblioteca del servidor quedan en la capa del contenedor y se pierden al recrearlo.
3. Se quita STIRLING_JVM_PROFILE. La 3.0 lo ignora y avisa en el arranque con "STIRLING_JVM_PROFILE is deprecated; use _JVM_OPTS or JAVA_BASE_OPTS instead".

El mem_limit no es nuevo, pero en mi prueba evitó un susto. La 2.14.3 con el perfil performance y sin límite ocupó 12,95 GiB nada más arrancar. Ese perfil reserva de golpe el 20 % de la memoria del equipo; con mem_limit: 4g se quedó en 2,21 GiB.

Con el archivo editado, arranca y consulta la versión:

docker compose up -d
curl -s http://127.0.0.1:8080/api/v1/info/status
{"version":"3.0.0","status":"UP"}

En el primer arranque, el registro muestra el aviso que más importa de toda la actualización: "Generated a new credential encryption key at ./configs/credential-encryption.key. Back this file up: losing it makes stored integration secrets and pipeline supporting files unrecoverable." Copia ese archivo junto al resto de tu copia en cuanto aparezca.

Qué comprobé después de actualizar

Todo lo que había creado en la 2.14.3 siguió en su sitio, con una sorpresa en el navegador. Estas son las comprobaciones que hice y su resultado:

• Login y sesión: la contraseña antigua funcionó y la sesión abierta del navegador sobrevivió, sin volver a entrar
• Usuarios: los 5 seguían ahí, y el sexto se rechazó igual que antes
• Clave de API: la misma clave extrajo el texto de una factura con /api/v1/convert/pdf/text
• API: la 3.0.0 publica 313 rutas frente a las 259 de la 2.14.3, y no ha desaparecido ninguna
• settings.yml: pasó de 35 964 a 44 371 bytes, con 66 claves nuevas y mis valores intactos; premium.proFeatures.ssoAutoLogin se mueve a security.ssoAutoLogin
• Carpeta vigilada: procesó otras 5 facturas con el mismo JSON de la 2.14.3
• Automatización del navegador: apareció en "Guardados" en el mismo navegador

La sorpresa fueron las traducciones. En el navegador que había usado la 2.14.3, la interfaz mostraba claves como processingFolders.setup.title en lugar de texto, y en una sesión limpia todo salía traducido.

El motivo está en las cabeceras: /locales/es-ES/translation.toml se sirve con max-age=86400, stale-while-revalidate=604800, así que el navegador usa la traducción de la 2.x hasta 8 días. Una recarga que se salte la caché la renueva; en mi prueba bastó con cargar la página con la caché desactivada. Avisa a tus usuarios o se encontrarán textos rotos al día siguiente de actualizar.

Tras la actualización también encontré un flujo "Classification" activado por defecto, configurado para clasificar con IA cada archivo que se sube al editor. El motor de IA viene desactivado y no comprobé qué hace ese flujo cuando lo activas, así que revísalo antes de encender la IA.

Procesar una carpeta, la automatización que sí encontré

La documentación del Processor de Stirling PDF^[5] indica que se abre desde la barra de acceso rápido de la izquierda. En el contenedor 3.0.0 que probé esa barra no mostraba ninguna entrada Processor, y la ruta /processor abría el editor. Lo que sí aparece es "Procesar una carpeta", que asocia un flujo de trabajo a una carpeta de la biblioteca del servidor.

Esa función necesita el almacenamiento en el servidor, que viene desactivado: el campo del nombre estaba bloqueado hasta que puse storage.enabled: true y reinicié. Con el almacenamiento activo, la carpeta ofrece cinco plantillas (Clasificación, Ingesta, Seguridad, Cumplimiento y Enrutamiento) y una sexta, Retención, que aparecía deshabilitada.

Ingesta hace OCR y, si la dejas activada, prepara fragmentos para búsqueda con IA, que requiere configurar el motor. Desactivé ese segundo paso para quedarme en el OCR, que usa inglés por defecto: cámbialo a español si escaneas documentos en castellano. Los archivos se guardan en subcarpetas de /storage, que es justo el volumen que añadiste al docker-compose.yml.

Mis dos primeras facturas se quedaron en estado PENDING más de 5 minutos. El endpoint /api/v1/admin/job/queue/stats respondía "resourceStatus":"CRITICAL", y el registro explicaba la causa: "CPU: 140.0%". Stirling-PDF divide la carga media del equipo entre los núcleos y retiene los trabajos por encima de 0,9. En un servidor compartido, sube el umbral con STIRLING_RESOURCE_CPU_CRITICALTHRESHOLD; con 5.0, las dos facturas terminaron en menos de 30 s tras reiniciar, con la carga media todavía en 25.

Si ya tenías el OCR de documentos resuelto con Paperless-ngx 3 y su IA local con Ollama, esta función no aporta mucho más y además gasta cupo. Donde encaja es en flujos que ya viven en Stirling-PDF.

¿Cómo vuelvo a la 2.14.3 si algo sale mal?

La vuelta atrás que funcionó fue restaurar la copia en frío. Con el contenedor parado, aparté la carpeta migrada, descomprimí la copia, que trae el docker-compose.yml con la etiqueta 2.14.3, y arranqué:

docker compose down
docker run --rm -v "$PWD":/stack -w /stack alpine sh -c \
  'mv data data-before-rollback && tar xzf stirling-backup-2.14.3.tar.gz'
docker compose up -d

El servidor volvió a responder {"version":"2.14.3","status":"UP"}, con los 6 usuarios de la base de datos (los 5 del plan y el usuario interno de la API) y la clave de API devolviendo 200. Pierdes lo que hiciste en la 3.0, incluidos los archivos del almacenamiento del servidor, pero conservas data-before-rollback por si necesitas recuperar algo.

También probé lo que no deberías hacer: arrancar la 2.14.3 sobre los datos ya migrados. En mi instalación pequeña arrancó y la clave de API funcionó, pero la guía oficial pide no dar por hecho que una versión antigua abre una base de datos migrada. Con PostgreSQL o muchos más datos, restaura la copia.

Preguntas frecuentes

¿Tengo que pasar por la 3.0.1 en Docker?

No. La 3.0.1 solo corrige dos fallos de la aplicación de escritorio de Windows, según sus notas de la versión 3.0.1^[6], y no existe como imagen de Docker. La etiqueta latest apunta a la 3.0.0.

¿El límite de 1000 PDF afecta al uso normal del editor?

No en mi prueba. Con el cupo agotado, una rotación hecha con la sesión del navegador devolvió 200, mientras la misma llamada con clave de API recibía 402. Las notas de la versión confirman que el uso normal del editor sigue siendo ilimitado.

¿Pierdo las automatizaciones que creé en la 2.x?

Las del diálogo "Automatizar" se guardan en tu navegador y siguen ahí en la 3.0 si usas el mismo navegador. Las carpetas vigiladas del servidor también siguen funcionando, aunque ya no tengan pantalla propia y ahora gasten cupo.

Conclusión

Actualizar Stirling-PDF a 3.0 con Docker es cambiar una etiqueta, y los datos sobreviven. El trabajo está alrededor: guardar credential-encryption.key, montar /storage antes de activar el almacenamiento, quitar STIRLING_JVM_PROFILE y avisar de la recarga forzada. Si tu instalación recibe llamadas por API, mide cuántas hace al mes antes de actualizar, porque a partir de la 1001 recibirán un 402 hasta que vincules el servidor o pagues. Si no tienes esa dependencia, haz la copia en frío, cambia a 3.0.0 y quédate con la vuelta atrás a mano un par de semanas mientras salen las versiones casi semanales que promete el proyecto.

Fuentes: [1] Stirling-Tools, notas de Stirling-PDF 3.0.0^[1], [2] Stirling-Tools, notas de Stirling-PDF 3.0.1^[6], [3] Stirling PDF, configuración y acceso al Processor^[5], [4] Stirling PDF, guía de migración^[3], [5] Docker Hub, etiquetas de stirlingtools/stirling-pdf^[2], [6] GitHub Container Registry, imagen stirling-pdf^[7], [7] Stirling PDF, planes de pago^[4], [8] Stirling PDF, instalación con Docker^[8], [9] Stirling PDF, orígenes de documentos del Processor^[9].

Fuentes

1. notas de Stirling-PDF 3.0.0
2. registro de etiquetas de Docker Hub
3. guía de migración de Stirling PDF
4. planes de pago de Stirling PDF
5. Processor de Stirling PDF
6. notas de la versión 3.0.1
7. GitHub Container Registry, imagen stirling-pdf
8. Stirling PDF, instalación con Docker
9. Stirling PDF, orígenes de documentos del Processor