Sign inSign up

dgongut/docker-controller-bot

By dgongut

•Updated 8 days ago

Bot de Telegram: Lleva el control de tus contenedores docker desde un único lugar.

Image
Web servers
Operating systems
Monitoring & observability
6

1M+

dgongut/docker-controller-bot repository overview

⁠Docker-Controller-Bot

Docker Pulls Docker Stars Docker Image Size Github stars Github forks Github last-commit Github last-commit

⁠ ReadMe en Español | ReadMe in English⁠ | Canal de Noticias en Telegram⁠

Lleva el control de tus contenedores Docker desde un único lugar: tu Telegram.

Docker-Controller-Bot

📦 Código fuente, incidencias y documentación completa en GitHub⁠.

NUEVO Canal de novedades en

⁠🚀 Empieza en 5 minutos

Solo hay dos pasos: crear tu bot y arrancarlo. Todo lo demás se configura después desde el propio chat.

⁠1. Crea tu bot en Telegram (2 min)
  1. Abre @BotFather⁠ en Telegram y envía /newbot. Sigue las instrucciones (un nombre y un username acabado en bot).
  2. BotFather te devolverá el token del bot. Guárdalo: irá en la variable TELEGRAM_TOKEN.
  3. Para conocer tu propio chat ID (lo necesitas para TELEGRAM_ADMIN), habla con @MissRose_bot⁠ y envíale /id. Te responderá con un número, ese es tu ID.
  4. (Opcional) Si vas a usar el bot dentro de un grupo, añádelo, hazlo administrador y obtén el chat ID del grupo de la misma forma; ese valor irá en TELEGRAM_GROUP.
  5. (Opcional) Si quieres ponerle el icono oficial al bot, descarga la imagen en alta resolución aquí⁠ y envíasela a @BotFather⁠ usando la opción /setuserpic.
⁠2. Arranca el contenedor (2 min)

Copia este docker-compose.yml, rellena las 3 variables y levántalo:

services:
    docker-controller-bot:
        environment:
            - TELEGRAM_TOKEN=
            - TELEGRAM_ADMIN=
            - TZ=Europe/Madrid
            #- TELEGRAM_GROUP=
            #- TELEGRAM_THREAD=1
            #- TELEMETRY=false # Descomenta para desactivar las estadísticas anónimas
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock # NO CAMBIAR
            - /ruta/para/guardar/la/configuracion:/app/config # CAMBIAR LA PARTE IZQUIERDA
            #- ~/.ssh:/root/.ssh:ro # Solo si vas a usar hosts remotos por ssh://
            #- ~/.docker/config.json:/root/.docker/config.json # Solo si se requiere iniciar sesión en algún registro
        image: dgongut/docker-controller-bot:latest
        container_name: docker-controller-bot
        restart: always
        network_mode: host
docker compose up -d

Abre Telegram, busca tu bot y envíale /start. Verás el menú principal con botones. Ya está: /list te muestra tus contenedores.

⚠️ Atención Es obligatorio mapear un volumen en /app/config: ahí se guardan los ajustes, las programaciones y la caché de actualizaciones. Sin ese volumen lo pierdes todo al recrear el contenedor.

ℹ️ Nota El bot envía una vez al día unas estadísticas anónimas⁠ de uso. Son opcionales: descomenta TELEMETRY=false en el compose, o desactívalas desde /settings → Estadísticas anónimas en los 10 minutos que el bot espera antes del primer envío.

🔄 ¿Vienes de la 4.x? No tienes que cambiar nada
  • Si tu docker-compose mapea /app/schedule (la ruta que se usaba hasta la 4.x) el bot lo detecta y sigue usándolo, así que actualizar no requiere cambiar nada y no perderás ni un ajuste.

  • Cuando quieras pasarlo a /app/config, es cambiar una letra de la línea del volumen:

    -  - /tu/ruta:/app/schedule
    +  - /tu/ruta:/app/config
    

    La misma parte izquierda, y no se mueve ningún fichero: los ficheros ya están en tu volumen y se llaman igual. Después, docker compose up -d para recrear el contenedor. Mientras no lo hagas, el bot te lo recuerda en su mensaje de arranque.

  • tty: true ya no hace falta. Hasta la 4.x el compose lo llevaba para que los logs del bot salieran en docker logs; desde la 5.0 la imagen los escribe al momento sin él. Puedes quitarlo, o dejarlo: no molesta.

  • CONTAINER_NAME ya no hace falta. Hasta la 4.x había que decirle al bot cómo se llamaba su propio contenedor, para que supiera no pararse ni eliminarse a sí mismo. Ahora lo averigua solo: lee su id en /proc/self/mountinfo y le pregunta a Docker cuál es. Si la tienes puesta el bot arranca igual y te avisa en el log de que puedes quitarla.

  • En el primer arranque el bot importa los valores de tus variables de entorno a settings.json y los conserva tal cual. A partir de ahí manda settings.json, y esas variables ya no se leen; el log te avisa de las que puedes borrar del docker-compose.

🔐 ¿Necesitas docker login (DockerHub, GHCR, registro privado)?

Si se requiere tener la sesión iniciada en algún registro, traslada ese login al contenedor mapeando tu ~/.docker/config.json a /root/.docker/config.json:

volumes:
    - ~/.docker/config.json:/root/.docker/config.json

⁠✨ ¿Qué puede hacer?

  • 📦 Contenedores: listar, arrancar, parar, reiniciar y eliminar. Con selección múltiple en /run, /stop y /restart.
  • 🧩 Compose: detecta tus proyectos y los agrupa (proyecto → contenedores).
  • 📊 Diagnóstico: logs en el chat o como fichero, exec dentro del contenedor, puertos e info detallada.
  • 🔄 Actualizaciones: te avisa si hay imagen nueva, actualiza uno o todos, cambia de tag (rollback) y deja que elijas, contenedor a contenedor, cuáles se actualizan solos y cuáles no se comprueban.
  • 🔔 Avisos: te dice cuándo un contenedor arranca, se para, se cae, se queda sin memoria o falla su healthcheck, y tú eliges de qué te avisa cada uno: todo, solo problemas o nada.
  • ⏰ Automatización: tareas programadas con cron + silencio temporal con /mute o desde un script con dcb-mute + limpieza con /prune.
  • 🖥️ Multi-host y ajustes: varios servidores desde un solo bot y todo configurable con /settings, sin reiniciar.
📋 Ver lista completa de funciones
  • ✅ Listar contenedores
  • ✅ Arrancar, parar y eliminar contenedores
  • ✅ Selección múltiple en /run, /stop y /restart: el menú se queda abierto y se va actualizando para encadenar varios contenedores
  • ✅ Soporte para proyectos Docker Compose con navegación jerárquica (proyecto → contenedores)
  • ✅ Obtener los logs tanto de manera directa como a través de fichero
  • ✅ Extraer el docker-compose de tus contenedores
  • ✅ Notificaciones cuando un contenedor se cae o se inicia
  • ✅ Avisos por contenedor: todos, solo problemas o ninguno, desde /info, /settings o la label DCB-Notifications
  • ✅ Notificaciones cuando un contenedor tiene una actualización pendiente
  • ✅ Actualizaciones de los contenedores
  • ✅ Cambiar el tag (rollback o actualización)
  • ✅ Limpia el sistema, eliminando contenedores, imágenes y otros objetos no utilizados
  • ✅ Ejecuta comandos dentro de contenedores
  • ✅ Visualiza puertos usados por contenedores, comprueba si un puerto concreto está libre y genera puertos aleatorios disponibles
  • ✅ Muestra información detallada de un contenedor o de un proyecto Compose completo
  • ✅ Programación de tareas con expresiones cron: run, stop, restart, exec, prune y mute
  • ✅ Varios hosts Docker desde un solo bot, por ssh://, tcp:// o TLS: se añaden desde el propio chat, y con un único host todo se ve exactamente igual que siempre
  • ✅ Se identifica a sí mismo sin ayuda: no hay que decirle cómo se llama su contenedor para que sepa no pararse ni eliminarse
  • ✅ Ajustes editables desde el propio bot con /settings, sin tocar el docker-compose ni reiniciar
  • ✅ Menú principal por botones en /start, agrupado en categorías; los comandos escritos siguen funcionando igual
  • ✅ Silencia las notificaciones de forma temporal, también desde un script con dcb-mute
  • ✅ Imagen multiarquitectura (amd64, arm64, armv7…) compatible con Raspberry Pi, NAS y servidores estándar
  • ✅ Soporte de idiomas (Spanish, English, Dutch, German, Russian, Galician, Italian, Catalan)

⁠📋 Comandos

Casi todos funcionan de dos formas: escribe el comando solo (/run) y el bot te muestra un menú con botones, o pásale el nombre directamente (/run nginx) para actuar sin menús.

/start abre el menú principal, con todo agrupado por categorías (Contenedores, Diagnóstico, Actualizaciones, Sistema, Automatización, Ajustes y Acerca de). Pulsar un botón hace exactamente lo mismo que escribir el comando a secas.

ComandoDescripción
/startMenú principal con botones, agrupados por tipo de acción
/listListado completo de contenedores, agrupados por host si tienes varios
/run /stop /restartArranca / detiene / reinicia un contenedor o un proyecto Compose entero
/deleteElimina un contenedor o un proyecto Compose entero
/execEjecuta un comando dentro de un contenedor
/logs /logfileLogs en mensaje o como fichero
/checkupdateComprueba si un contenedor tiene actualización
/updateallActualiza todos los contenedores, de todos los hosts a la vez
/changetagCambia el tag de la imagen (rollback o salto de versión)
/composeExtrae el docker-compose de un contenedor o proyecto
/infoMuestra información detallada de un contenedor o de un proyecto
/portsLista puertos usados, comprueba uno concreto o genera uno libre
/pruneLimpia contenedores, imágenes, redes o volúmenes no usados
/mute <minutos>Silencia las notificaciones durante X minutos
/scheduleMenú para crear, editar y borrar tareas programadas
/settingsAjustes del bot: idioma, columnas, comprobación de actualizaciones, canal de notificaciones y hosts de Docker
/version /donate /donorsVersión actual / donar / lista de donantes
🧩 Mis contenedores son de docker compose, ¿cómo se ven?

Si tus contenedores fueron creados con docker compose, el bot los reconoce automáticamente como un proyecto y los presenta agrupados.

En comandos como /run, /stop, /restart, /delete, /info o /compose verás primero la lista de proyectos y, al pulsar uno, sus contenedores. En /run y /stop solo se ofrecen los servicios sobre los que la acción tiene sentido (parados y arrancados respectivamente), igual que ya indicaba el contador del botón del proyecto. Las acciones de inicio, parada, reinicio y borrado se pueden aplicar al proyecto entero o a un contenedor individual.

⏰ Automatizar tareas con /schedule

Desde /schedule puedes crear tareas que se ejecuten en cron.

  • Acciones soportadas: run, stop, restart, exec, prune y mute.
  • Acepta expresiones cron estándar (0 */4 * * *) y atajos: @yearly, @monthly, @weekly, @daily, @hourly y @reboot.
  • Si tienes varios hosts, el bot te pregunta en cuál se ejecuta la tarea, y el host aparece en el resumen y en el listado. mute es la excepción: silencia las notificaciones del propio bot, así que no pertenece a ninguna máquina.
  • Las programaciones se persisten en /app/config (recuerda mapear ese volumen).
⚙️ Configuración avanzada y /settings

Aquí solo quedan las variables que el bot necesita antes de poder leer sus propios ajustes: cómo llegar a Telegram y quién puede hablarle. La regla es sencilla: si ponerla mal te puede dejar sin acceso al bot, va en el docker-compose, porque lo que impide que el chat funcione no se puede arreglar desde el chat.

CLAVEOBLIGATORIOVALOR
TELEGRAM_TOKEN✅Token del bot
TELEGRAM_ADMIN✅ChatId del administrador (se puede obtener hablándole al bot Rose⁠ escribiendo /id). Admite múltiples administradores separados por comas. Por ejemplo 12345,54431,55944
TELEGRAM_GROUP❌ChatId del grupo. Si este bot va a formar parte de un grupo, es necesario especificar el chatId de dicho grupo. Es necesario que el bot sea administrador del grupo
TELEGRAM_THREAD❌Thread del tema dentro de un supergrupo; valor numérico (2,3,4..). Por defecto 1. Se utiliza en conjunción con la variable TELEGRAM_GROUP
TZ✅Timezone (Por ejemplo Europe/Madrid)
TELEMETRY❌false para desactivar las estadísticas anónimas sin pasar por /settings. Lo normal es desactivarlas desde /settings; esto es para quien prefiera dejarlo fijado en el compose

Todo lo demás se configura desde el propio bot y se guarda en settings.json, dentro del volumen mapeado:

AJUSTEVALOR
IdiomaES / EN / NL / DE / RU / GL / IT / CAT. Por defecto ES
Columnas de botonesNúmero de columnas en las listas de contenedores. Por defecto 2
Mensajes ampliadosMuestra más mensajes de información. Por defecto desactivado
Selección múltipleEn /run, /stop y /restart el menú se queda abierto para actuar sobre varios contenedores seguidos. Por defecto activado
Comprobar actualizacionesPor defecto activado
Intervalo de comprobaciónHoras entre comprobaciones. Acepta decimales. Por defecto 4
Contenedores paradosSi comprueba también las actualizaciones de los contenedores detenidos. Por defecto activado
Por contenedorQué contenedores se actualizan solos y cuáles no se comprueban. También desde el /info de cada uno. Por defecto ninguno: avisa de todos
Canal de notificacionesCanal donde se publicarán exclusivamente los cambios de estado de los contenedores (arranque, parada, creación y actualizaciones automáticas). La gestión se sigue haciendo desde el chat privado con el bot o desde TELEGRAM_GROUP. El bot comprueba que puede publicar ahí antes de guardarlo
Hosts de DockerLas máquinas que gestiona el bot. Se añaden, se prueban, se renombran, se les cambia la URL y se quitan desde aquí. Ver desplegable de hosts remotos
Estadísticas anónimasUna vez al día envía cifras anónimas de uso. Por defecto activado. Ver Estadísticas anónimas⁠

Los cambios hechos desde /settings se aplican al momento, sin reiniciar el contenedor.

🖥️ ¿Tienes más de un servidor? Gestiona varios hosts Docker

A partir de la 5.0.0 el bot puede gestionar varios hosts Docker. Se definen en los ajustes, no en variables de entorno, así que se añaden desde el propio bot sin tocar el docker-compose.

Con un solo host —el caso normal— nada de esto aparece: el bot se ve exactamente igual que en la 4.x.

⁠Cómo conectar con un host remoto

Hay dos formas, y para la mayoría de la gente la primera es la respuesta:

FormaQué necesitaCuándo
ssh://usuario@maquinaNada en el host remoto salvo su sshd de siempreLa recomendada. Si ya entras por ssh a esa máquina, ya está medio hecho
tcp://maquina:2375Un socket proxy en la máquina remotaSi tus máquinas ya están en una red privada (Tailscale, WireGuard, una VLAN aislada)

⚠️ Aviso: tcp:// sin TLS no tiene autenticación de ningún tipo: cualquiera que alcance ese puerto controla el Docker de esa máquina por completo, con permisos equivalentes a root. Solo dentro de una red en la que confíes, nunca expuesto a internet.

ℹ️ Nota: Docker también admite tcp:// cifrado con TLS. Es bastante más trabajo y con ssh:// disponible no le veo la necesidad, pero si tu caso lo pide está explicado en la FAQ⁠, en «Quiero usar tcp:// pero cifrado con TLS».

La guía paso a paso (cómo comprobar la conexión, ssh://, socket proxy, varios servidores y NAS) está en GitHub⁠.

⁠Las credenciales nunca se guardan en los ajustes

En settings.json solo va la URL y, para TLS, las rutas de los certificados. Ni claves ni contraseñas: el material sensible son ficheros que tú mapeas, y así ningún mensaje de Telegram acaba llevándolo dentro.

🔄 Contenedores que se actualizan solos o que no se comprueban

Por defecto, cuando hay una versión nueva el bot te avisa. Para cada contenedor puedes elegir otra cosa:

  • 🔄 Actualizar solo: se actualiza sin preguntar en cuanto la comprobación encuentra una versión nueva. Todos los de una misma comprobación van juntos, en un único mensaje de resumen, como si los hubieras marcado tú en /updateall.
  • 🚫 No comprobar: la comprobación no lo mira: ni avisos, ni /updateall.

Se elige desde el bot, de dos formas, y en las dos cada toque pasa al siguiente (avisar → actualizar solo → no comprobar):

  • En el /info de un contenedor, con el botón 🤖 - Versión nueva.
  • Para muchos a la vez, en /settings → Actualizaciones → 📦 Por contenedor, con la lista de contenedores: 🔔 avisa · 🔄 se actualiza solo · 🚫 no se comprueba.

Se guarda en settings.json por host y por nombre de contenedor, así que se conserva aunque el contenedor se recree o se actualice. Si lo borras con /delete, o borrando su proyecto, se olvida al momento. Si desaparece de cualquier otra forma (también con /prune), se olvida cuando lleva 30 días sin aparecer en un host que responde, y el bot te lo dice. Mientras un host no responde o está en pausa, lo suyo no se toca; al quitar un host, se va con él.

También sirven las labels de siempre, DCB-Auto-Update y DCB-Ignore-Check-Updates. Si un contenedor lleva una de ellas, manda la label, aunque valga false: en el bot sale con 🏷️ y se cambia en su compose. Ver ejemplo completo en la FAQ: «He visto que se pueden añadir labels…».

🔔 De qué avisa cada contenedor

Por defecto el bot avisa de todo lo que le pasa a un contenedor: cuando arranca, cuando se para, cuando falla. Para cada uno puedes elegir menos:

  • ⚠️ Solo problemas: calla los arranques, las paradas que se piden (un docker stop, el bot, una tarea, un script de copia de seguridad) y los procesos que terminan bien, y sigue avisando de lo que falla: una caída con código distinto de 0, la falta de memoria, un healthcheck que falla y cuando vuelve a ir, y los bucles de reinicio.
  • 🔕 Ninguno: no avisa de nada de ese contenedor.

Se elige en el /info de un contenedor, con el botón 🤖 - Avisos, o para muchos a la vez en /settings → 🔔 Avisos por contenedor. Se guarda igual que lo de las actualizaciones, y también se puede poner en el compose con la label DCB-Notifications=problems o DCB-Notifications=none, que manda sobre lo elegido en el bot.

Lo que pidas tú desde el bot (arrancar, parar, reiniciar) te lo confirma igualmente. Y no gasta nada: el bot lo decide con la label que ya viene en cada evento de Docker y con los ajustes que tiene en memoria, sin preguntar nada más a Docker.

⁠📊 Estadísticas anónimas

Desde la 5.0.0 el bot envía una vez al día unas cifras anónimas para saber cuánta gente lo usa, en cuántos hosts y qué funciones se usan más. Así sé dónde poner el esfuerzo. Las estadísticas son públicas: stats.dgongut.com/docker-controller-bot⁠.

Son opcionales. Vienen activadas por defecto y se desactivan de dos formas:

  • Desde el bot: /settings → Estadísticas anónimas. Al desactivarlas se borra también el identificador de la instalación.
  • Desde el compose: TELEMETRY=false.

Nada se envía hasta que el bot lleva al menos 10 minutos en marcha, así que da tiempo de sobra a desactivarlas desde /settings antes del primer envío.

Qué se envía y qué no

Qué se envía: cuántos hosts y contenedores hay (los contenedores, por tramos), qué ajustes están activados, la versión del bot y de Docker, la arquitectura, y cuántas veces al día se ha usado cada comando y cada botón. En /settings → Estadísticas anónimas → Qué se envía puedes ver el envío exacto que saldría ahora mismo. La lista completa, campo a campo, está en la página de privacidad⁠. El servidor descarta cualquier dato que no esté en ella.

Qué no se envía nunca: nombres de contenedores, imágenes, hosts o proyectos, direcciones, IDs de Telegram, rutas ni nada de lo que escribes. Tu IP no se guarda.

El código es abierto: el cliente que envía los datos⁠ y el servidor que los recibe⁠.

Tampoco se envía nada si la configuración no está en un volumen, porque sin él cada vez que se recreara el contenedor contaría como una instalación nueva.

⁠❓ Preguntas Frecuentes (FAQ)

Las preguntas frecuentes (versiones de las imágenes, labels, varios hosts, tcp:// con TLS...) están en GitHub⁠.

Tag summary

Content type

Image

Digest

sha256:2678c5378…

Size

35.5 MB

Last updated

8 days ago

docker pull dgongut/docker-controller-bot