StirlingPDFAssistant: Un Bot de Telegram para Manipular PDFs desde tu Móvil

Hace unos meses compartí un post sobre Stirling PDF, una herramienta que me permitió dejar de depender de servicios como iLovePDF para manipular mis documentos. La instalé en mi Raspberry Pi 4 con Docker, la olvidé y funcionó perfectamente por meses.

Pero había un pequeño detalle: solo podía usarla desde el navegador. Sonaba trivial hasta que me vi en la necesidad de comprimir un PDF urgente desde el celular, estando fuera de casa, y tuve que abrir Chrome, escribir la IP, navegar la interfaz web — todo desde la pantalla del teléfono. Funcionaba, pero no era cómodo.

Ahí fue donde se me ocurrió construir un bot de Telegram que hiciera de puente entre mi teléfono y mi instancia de Stirling PDF. El resultado es StirlingPDFAssistant.

¿Qué es StirlingPDFAssistant?

Es un bot de Telegram que se conecta a tu instancia self-hosted de Stirling PDF. Le envías un PDF y te responde con un menú de operaciones disponibles: comprimir, convertir a Word, añadir contraseña, dividir páginas, aplicar OCR, combinar varios documentos y mucho más. Todo sin abrir un navegador.

Está escrito en Python, optimizado para Raspberry Pi (por defecto solo ejecuta dos tareas simultáneas para no saturar el procesador), y soporta inglés y español de forma automática según el idioma que tengas configurado en Telegram.

¿Por qué un bot y no la web?

Honestamente, la interfaz web de Stirling PDF es impecable y si estás en el escritorio no necesitas nada más. Pero el bot resuelve varios problemas que probablemente muchos hemos enfrentado:

Privacidad. Aunque Stirling PDF ya es self-hosted, el bot mantiene todo el flujo dentro de tu red privada. El PDF viaja de Telegram a tu servidor local y nunca toca una nube externa. Si eres de los que no duerme tranquilo subiendo documentos sensibles a servicios de terceros, esto te va a gustar.

Acceso desde cualquier lado. Telegram está en tu móvil, en tu tablet, en el escritorio. No necesitas recordar IPs, abrir puertos ni configurar VPNs. El bot está en tu lista de chats, siempre disponible.

Control de acceso. El bot tiene un sistema de usuarios autorizados. Si alguien que no está en la lista intenta usarlo, ve un botón de "Solicitar Acceso" que te notifica para que apruebes o rechaces la solicitud. Ideal si quieres compartir la instancia con la familia o un equipo pequeño.

¿Qué puede hacer?

La lista de operaciones es bastante completa. De las que más uso personalmente:

• Comprimir PDF — reducir el tamaño cuando un archivo pesa demasiado para enviarlo por correo.
• OCR — convertir escaneos en texto buscable. Soporta varios idiomas (inglés, español, entre otros).
• Añadir contraseña — proteger con cifrado de 40, 128 o 256 bits.
• Convertir a Word — pasa tu PDF a DOCX (también soporta DOC y ODT).
• Efecto escáner — para cuando necesitas que un PDF digital parezca un documento escaneado.
• Dividir PDF — extraer páginas específicas por rango.
• Auto-redactar — ocultar palabras clave automáticamente.
• Combinar PDFs — el modo merge te permite encolar varios PDFs e imágenes para unirlos en un solo documento.
• URL a PDF — envía un enlace y recibes una página completa en PDF.
• Markdown a PDF — para los que escribimos documentación en .md.
• Imagen a PDF — útil cuando solo tienes una foto de un documento.
• Documentos a PDF — convierte archivos de Office (DOCX, PPT, XLS) usando LibreOffice.

¿Cómo funciona por dentro?

El bot sigue un flujo bastante simple: tú envías un archivo, el servidor del bot corriendo en la Raspberry Pi lo carga en memoria, lo envía a tu instancia de Stirling PDF a través de su API, recibe el resultado y te lo devuelve como un documento nuevo. Todo de forma asíncrona para no bloquear otras operaciones.

Lo interesante es que está diseñado con un patrón de herramientas inspirado en el Model Context Protocol (MCP). Cada operación de PDF es una clase independiente que sabe exactamente qué parámetros necesita y cómo construir la petición a la API. Si en el futuro quiero agregar una nueva operación, solo creo una nueva clase y el bot la detecta automáticamente.

Despliegue

Al igual que Stirling PDF, el bot se despliega con Docker. Solamente necesitas clonar el repositorio, configurar un par de variables y ejecutar docker-compose:

git clone https://github.com/AudelDiaz/StirlingPDFAssistant.git
cd StirlingPDFAssistant
cp .env.example .env

Dentro del archivo .env configuras tu token de Telegram, la URL de tu instancia de Stirling PDF y el ID de tu usuario de Telegram para ser el dueño del bot:

TELEGRAM_BOT_TOKEN=tu-token-de-botfather
STIRLING_PDF_URL=http://192.168.1.100:8080
STIRLING_PDF_API_KEY=tu-api-key
BOT_OWNER_ID=tu-id-de-telegram

Y finalmente:

docker-compose up -d

Para los que prefieren evitar Docker, también funciona directamente con Python usando uv.

CI/CD: Calidad y Seguridad Automatizadas

Uno de los aspectos que más me interesó al construir este proyecto fue asegurarme de que cada cambio que llega al repositorio pase por una serie de verificaciones antes de que la imagen se publique. El pipeline de CI/CD está montado sobre GitHub Actions y tiene varios gates que actúan como filtros de calidad:

Build multi-arquitectura. La imagen se compila para linux/amd64 y linux/arm64 en paralelo, lo que significa que funciona tanto en un servidor x86 como en una Raspberry Pi sin necesidad de recompilar.

Escaneo de vulnerabilidades con Trivy. Después de construir la imagen, Trivy analiza las capas del contenedor buscando vulnerabilidades conocidas en las dependencias del sistema. Si encuentra alguna de nivel CRITICAL o HIGH, el pipeline se detiene y no se publica nada. Esto obliga a mantener las dependencias actualizadas y a no subir imágenes con agujeros de seguridad conocidos.

Publicación en GitHub Container Registry. Solo si todos los gates pasan, la imagen se publica en ghcr.io con el tag correspondiente. El contenedor corre como usuario no-root (UID 1000) para reducir la superficie de ataque en caso de que alguien logre ejecutar código dentro del contenedor.

En la práctica, esto significa que cada push a main, pull request, o cada tag de versión pasa por un proceso automatizado que garantiza que lo que se despliega es seguro, reproducible y compatible con múltiples arquitecturas. Sin intervención manual, sin olvidos.

¿Para quién es esto?

• Si ya corres o quieres correr Stirling PDF en una Raspberry Pi o servidor local y quieres acceder desde el exterior sin agregar nuevos riesgos de seguridad.
• Si compartes una instancia con tu familia o equipo y necesitas controlar quién la usa.
• Si te importa la privacidad y prefieres evitar que documentos sensibles toquen servicios en la nube.
• Si simplemente eres de los que prefieren un bot de Telegram a una interfaz web.

Debo confesar que al principio pensé que era una solución demasiado específica, pero con el tiempo se volvió una de esas herramientas que uno no sabía que necesitaba hasta que las tiene.

El proyecto es completamente open source (MIT) y está en github.com/AudelDiaz/StirlingPDFAssistant. Si tienes ideas, encuentras algún bug o simplemente quieres dejar una estrella, eres bienvenido.

Gracias por llegar hasta este punto, nos vemos en el próximo post.