Cómo instalar y configurar Stirling

1. Qué es Stirling-PDF y por qué es necesario en su propio servidor

Para 2026, la cuestión de la privacidad de los datos se ha vuelto crítica. Cada vez que carga un documento en un servicio en línea gratuito para "combinar PDF rápidamente", está entregando sus datos personales, informes financieros o secretos corporativos a terceros. Stirling-PDF es una solución de código abierto que traslada la funcionalidad de los editores de PDF profesionales a su navegador, funcionando exclusivamente en su propio hardware.

A diferencia de las aplicaciones de escritorio, Stirling-PDF es accesible desde cualquier dispositivo: smartphone, tableta o portátil. A diferencia de las soluciones SaaS, aquí no hay suscripciones, límites en el número de páginas o "funciones premium". Usted obtiene el control total sobre el proceso de procesamiento.

Funciones clave:

• Combinar, dividir, rotar y eliminar páginas.
• Compresión de PDF con elección de algoritmos de optimización.
• Adición de marcas de agua, firmas y sellos.
• Conversión de PDF a formatos Word, Excel, PowerPoint, HTML y viceversa.
• OCR (Optical Character Recognition): conversión de escaneos en documentos de texto con capacidad de búsqueda.
• Eliminación de contraseñas y establecimiento de nuevas (AES-256).
• Herramientas para organizar páginas: cambio de orden, numeración, recorte.

El self-hosting en un VPS le brinda independencia de las sanciones de los proveedores, una velocidad de procesamiento estable (que depende solo de los recursos de su servidor) y la seguridad de que sus archivos no se utilizan para entrenar redes neuronales sin su consentimiento.

2. Qué configuración de VPS se necesita para esta tarea

Stirling-PDF es una aplicación Java (Spring Boot) que utiliza activamente bibliotecas externas como LibreOffice y Tesseract OCR. Estos componentes exigen recursos, especialmente durante la conversión de archivos voluminosos o el reconocimiento de texto en alta resolución.

Para un funcionamiento estable del OCR, especialmente si planea procesar documentos de más de 100 páginas, la cantidad de memoria RAM es crítica. El proceso Java puede consumir recursos significativos en picos de carga. Para un trabajo cómodo sin retrasos, puede elegir un VPS adecuado con 4 u 8 GB de RAM; esto asegurará un funcionamiento fluido de la interfaz y un procesamiento rápido de las colas de tareas.

¿Cuándo elegir un servidor dedicado? Si su tarea es el procesamiento automatizado de miles de documentos al día a través de la API de Stirling-PDF, o si está construyendo un servicio corporativo interno para una plantilla de más de 50 empleados. En los demás casos, un VPS moderno será más que suficiente.

Ubicación: Elija un servidor lo más cerca posible de usted o de su audiencia objetivo. Aunque el procesamiento de PDF ocurre en el backend, la latencia (latency) afecta la velocidad de carga y descarga de archivos pesados.

3. Preparación del servidor: fortalecimiento básico y utilidades

Antes de instalar la aplicación en sí, es necesario preparar el entorno. Utilizaremos Ubuntu 24.04, pero las instrucciones son aplicables a versiones más recientes de 2026.

En primer lugar, actualizaremos los paquetes e instalaremos el conjunto básico de herramientas:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget git htop ufw fail2ban

La configuración de seguridad es una etapa importante. Cerraremos todos los puertos excepto SSH y los puertos web estándar:

# Permitimos SSH (¡asegúrese de tener acceso!)
sudo ufw allow 22/tcp
# Permitimos HTTP y HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
# Activamos el firewall
sudo ufw enable

Para prevenir ataques de fuerza bruta en SSH, configuraremos fail2ban. Crearemos una configuración local:

sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

También se recomienda crear un usuario separado con privilegios sudo para no trabajar como root constantemente:

adduser pdfadmin
usermod -aG sudo pdfadmin
# Cambiamos al nuevo usuario
su - pdfadmin

4. Instalación de Docker y Docker Compose (actualizado a 2026)

Stirling-PDF se distribuye oficialmente como una imagen de Docker. Es la forma ideal de instalación, ya que incluye todas las dependencias (Python, LibreOffice, Java, Tesseract) en un contenedor aislado, sin "ensuciar" el sistema principal.

Instalaremos Docker mediante el script oficial:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Añadiremos a nuestro usuario al grupo docker para ejecutar contenedores sin sudo:

sudo usermod -aG docker $USER
# Aplique los cambios de grupo (o vuelva a entrar en SSH)
newgrp docker

Verificaremos la instalación:

docker compose version
docker --version

En 2026, Docker Compose es una parte integrada del comando docker (plugin compose), por lo que ya no se requiere una instalación por separado de docker-compose.

5. Despliegue de Stirling-PDF: instrucciones paso a paso

Utilizaremos Stirling-PDF-Ultra, que es la versión más completa de la imagen, incluyendo todos los idiomas de OCR y herramientas adicionales. Crearemos un directorio de trabajo:

mkdir -p ~/stirling-pdf/configs ~/stirling-pdf/logs
cd ~/stirling-pdf

Crearemos el archivo docker-compose.yml. En este archivo describiremos los parámetros de inicio de la aplicación:

nano docker-compose.yml

Inserte el siguiente contenido:

services:
  stirling-pdf:
    image: frooodle/s-pdf:latest-ultra
    container_name: stirling-pdf
    restart: always
    ports:
      - "8080:8080"
    environment:
      - DOCKER_ENABLE_SECURITY=true
      - INSTALL_BOOK_AND_ADVANCED_HTML_OPS=true
      - LANGS=ru_RU,en_GB
      - APP_LOCALE=ru_RU
      - SYSTEM_DEFAULT_LOCALE=ru_RU
      - TZ=Europe/Moscow
    volumes:
      - ./configs:/configs
      - ./logs:/logs
      - /usr/share/tesseract-ocr/4.00/tessdata:/usr/share/tesseract-ocr/4.00/tessdata # Opcional para diccionarios propios

Analicemos las variables de entorno clave:

• DOCKER_ENABLE_SECURITY: activa el sistema de autorización (usuario/contraseña). Por defecto, el usuario es admin y la contraseña es stirling. ¡Asegúrese de cambiarla después del primer inicio!
• LANGS: lista de idiomas para OCR. Hemos especificado ruso e inglés.
• INSTALL_BOOK_AND_ADVANCED_HTML_OPS: activa el soporte para la conversión de libros electrónicos y operaciones avanzadas con HTML.

Iniciamos el contenedor:

docker compose up -d

Puede verificar el estado del inicio con el comando docker ps o viendo los logs: docker logs -f stirling-pdf. En el primer inicio, la descarga de la imagen "Ultra" puede tardar unos minutos, ya que pesa alrededor de 2-3 GB debido a LibreOffice integrado y los paquetes de idiomas.

6. Configuración del acceso a través de HTTPS (Caddy)

Ejecutar el servicio en el puerto 8080 sin cifrado es una mala idea, especialmente si trabaja con documentos. Necesitamos HTTPS. La forma más sencilla y moderna es utilizar el servidor web Caddy, que obtiene y renueva automáticamente los certificados SSL de Let's Encrypt.

Instalemos Caddy:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1G 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1G 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

Configuremos el proxy. Edite el archivo /etc/caddy/Caddyfile:

sudo nano /etc/caddy/Caddyfile

Reemplace el contenido con lo siguiente (indique su dominio):

pdf.yourdomain.com {
    reverse_proxy localhost:8080
    
    encode gzip
    
    log {
        output file /var/log/caddy/pdf_access.log
    }
}

Reinicie Caddy:

sudo systemctl restart caddy

Ahora, siempre que el registro A de su dominio apunte a la IP de su VPS, el servicio estará disponible en la dirección https://pdf.yourdomain.com con un certificado SSL válido.

7. Configuración avanzada: OCR, localización y seguridad

Stirling-PDF permite ajustar con precisión el proceso de reconocimiento de texto. El OCR se basa en el motor Tesseract. Si descubre que la calidad del reconocimiento del idioma ruso no es lo suficientemente alta, puede añadir datos de entrenamiento adicionales.

Configuración de la autorización

Después del primer inicio de sesión, vaya a la sección Settings -> Security Settings. Aquí puede:

• Cambiar la contraseña de administrador predeterminada.
• Habilitar claves API para la integración con otros servicios (por ejemplo, para la automatización mediante scripts de Python o n8n).
• Configurar el tiempo de vida de la sesión.

Optimización del rendimiento

Si el servidor comienza a "ralentizarse" al procesar archivos PDF, puede limitar los recursos del contenedor en docker-compose.yml:

    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 4G

Esto evitará situaciones en las que un solo archivo pesado "bloquee" todo el VPS, privándole del acceso por SSH.

Fuentes personalizadas

Para la visualización correcta del cirílico al convertir de PDF a Word/HTML, a veces se requieren fuentes específicas. Puede montar la carpeta de fuentes de su servidor en el contenedor:

      - /usr/share/fonts:/usr/share/fonts:ro

8. Copias de seguridad y actualización automática del sistema

Aunque Stirling-PDF no almacena sus documentos para siempre de forma predeterminada (se eliminan del almacenamiento temporal después del procesamiento), es necesario realizar copias de seguridad de la configuración de la aplicación, los usuarios y las marcas de agua personalizadas.

Script de copia de seguridad

Crearemos un script sencillo backup.sh:

#!/bin/bash
BACKUP_DIR="/home/pdfadmin/backups"
DATE=$(date +%Y-%m-%d)
mkdir -p $BACKUP_DIR

# Detenemos el contenedor para la consistencia de los datos (opcional)
cd /home/pdfadmin/stirling-pdf
docker compose stop

# Archivado de configuraciones
tar -czf $BACKUP_DIR/stirling_conf_$DATE.tar.gz ./configs

# Inicio del contenedor
docker compose start

# Eliminación de copias de seguridad antiguas (más de 30 días)
find $BACKUP_DIR -type f -mtime +30 -delete

Añada el script a crontab para su ejecución diaria a las 3 de la mañana:

0 3   * /bin/bash /home/pdfadmin/stirling-pdf/backup.sh

Actualización de Stirling-PDF

Los desarrolladores lanzan actualizaciones activamente. Para actualizar a la última versión, ejecute:

cd ~/stirling-pdf
docker compose pull
docker compose up -d --remove-orphans

Docker descargará automáticamente las nuevas capas de la imagen y reiniciará el servicio conservando todos sus ajustes (ya que se almacenan en volúmenes externos).

9. Solución de problemas + FAQ

¿Por qué el OCR funciona muy lento?

El OCR es un proceso que carga al máximo la CPU. Si su VPS solo tiene 1 o 2 núcleos, el reconocimiento de un documento de 50 páginas puede tardar varios minutos. Compruebe la carga con el comando htop. Si la CPU está al 100%, considere la posibilidad de mejorar el plan de su VPS.

Error "Out of Memory" al cargar archivos grandes

Esto se debe a los límites de Java Heap Size. Puede aumentar el límite añadiendo una variable en docker-compose.yml:

      - JAVA_OPTS=-Xmx2g

Esto asignará 2 GB de memoria RAM específicamente para las necesidades del proceso Java.

¿Qué configuración de VPS es la mínima adecuada?

El mínimo es 2 núcleos de CPU y 4 GB de RAM. Con 2 GB de RAM la aplicación se iniciará, pero al intentar usar OCR o convertir PDF a DOCX, es muy probable que el sistema detenga el contenedor (OOM Killer).

¿Qué elegir: VPS o dedicado para esta tarea?

Para uso personal y equipos pequeños (hasta 10 personas), un VPS es la elección ideal. Es flexible y fácil de escalar. Un servidor dedicado solo vale la pena si planea procesar archivos de documentos enormes (decenas de miles de páginas al día), donde la multitarea y la ausencia de "vecinos" en el hipervisor son importantes.

¿Es seguro almacenar documentos en el servidor?

Stirling-PDF está diseñado para eliminar los archivos inmediatamente después de cerrar la página o descargar el resultado. Sin embargo, para una seguridad máxima, asegúrese de utilizar HTTPS y una contraseña compleja para acceder al sistema.

¿Cómo añadir soporte para otros idiomas de OCR?

En la variable LANGS del archivo docker-compose.yml, añada los códigos necesarios separados por comas (por ejemplo, deu para alemán, fra para francés). La lista completa de códigos está disponible en la documentación de Tesseract.

10. Conclusiones y próximos pasos

Hemos desplegado con éxito una herramienta profesional de gestión de PDF en nuestro propio servidor. Ahora tiene el control total sobre sus documentos, sin suscripciones y con un potente motor de OCR disponible desde cualquier lugar del mundo.

¿Qué hacer a continuación?

• Integración: Intente utilizar la API de Stirling-PDF para automatizar tareas rutinarias. Por ejemplo, puede configurar un script que aplique automáticamente una marca de agua a todos los PDF de una carpeta específica.
• Aplicación móvil: Dado que la interfaz es adaptativa, puede añadir un acceso directo a la página en la pantalla de su smartphone; funcionará como una aplicación PWA completa.
• Optimización: Si planea el acceso público, configure Cloudflare delante de su VPS para protegerse contra ataques DDoS y obtener un almacenamiento en caché adicional de los elementos estáticos.

El autoalojamiento (self-hosting) no es solo un ahorro de dinero, sino también un paso importante hacia la soberanía digital. Con Stirling-PDF, sus datos le pertenecen solo a usted.