Bot de Telegram: Lleva el control de tus contenedores docker desde un único lugar.
1M+
Lleva el control de tus contenedores Docker desde un único lugar: tu Telegram.

📦 Código fuente, incidencias y documentación completa en GitHub.
Solo hay dos pasos: crear tu bot y arrancarlo. Todo lo demás se configura después desde el propio chat.
/newbot. Sigue las instrucciones (un nombre y un username acabado en bot).TELEGRAM_TOKEN.TELEGRAM_ADMIN), habla con @MissRose_bot y envíale /id. Te responderá con un número, ese es tu ID.TELEGRAM_GROUP./setuserpic.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=falseen el compose, o desactívalas desde/settings→ Estadísticas anónimas en los 10 minutos que el bot espera antes del primer envío.
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.
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
/run, /stop y /restart.exec dentro del contenedor, puertos e info detallada./mute o desde un script con dcb-mute + limpieza con /prune./settings, sin reiniciar./run, /stop y /restart: el menú se queda abierto y se va actualizando para encadenar varios contenedores/info, /settings o la label DCB-Notificationsssh://, tcp:// o TLS: se añaden desde el propio chat, y con un único host todo se ve exactamente igual que siempre/settings, sin tocar el docker-compose ni reiniciar/start, agrupado en categorías; los comandos escritos siguen funcionando igualdcb-muteCasi 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.
| Comando | Descripción |
|---|---|
/start | Menú principal con botones, agrupados por tipo de acción |
/list | Listado completo de contenedores, agrupados por host si tienes varios |
/run /stop /restart | Arranca / detiene / reinicia un contenedor o un proyecto Compose entero |
/delete | Elimina un contenedor o un proyecto Compose entero |
/exec | Ejecuta un comando dentro de un contenedor |
/logs /logfile | Logs en mensaje o como fichero |
/checkupdate | Comprueba si un contenedor tiene actualización |
/updateall | Actualiza todos los contenedores, de todos los hosts a la vez |
/changetag | Cambia el tag de la imagen (rollback o salto de versión) |
/compose | Extrae el docker-compose de un contenedor o proyecto |
/info | Muestra información detallada de un contenedor o de un proyecto |
/ports | Lista puertos usados, comprueba uno concreto o genera uno libre |
/prune | Limpia contenedores, imágenes, redes o volúmenes no usados |
/mute <minutos> | Silencia las notificaciones durante X minutos |
/schedule | Menú para crear, editar y borrar tareas programadas |
/settings | Ajustes del bot: idioma, columnas, comprobación de actualizaciones, canal de notificaciones y hosts de Docker |
/version /donate /donors | Versión actual / donar / lista de donantes |
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.
/scheduleDesde /schedule puedes crear tareas que se ejecuten en cron.
run, stop, restart, exec, prune y mute.0 */4 * * *) y atajos: @yearly, @monthly, @weekly, @daily, @hourly y @reboot.mute es la excepción: silencia las notificaciones del propio bot, así que no pertenece a ninguna máquina./app/config (recuerda mapear ese volumen)./settingsAquí 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.
| CLAVE | OBLIGATORIO | VALOR |
|---|---|---|
| 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:
| AJUSTE | VALOR |
|---|---|
| Idioma | ES / EN / NL / DE / RU / GL / IT / CAT. Por defecto ES |
| Columnas de botones | Número de columnas en las listas de contenedores. Por defecto 2 |
| Mensajes ampliados | Muestra más mensajes de información. Por defecto desactivado |
| Selección múltiple | En /run, /stop y /restart el menú se queda abierto para actuar sobre varios contenedores seguidos. Por defecto activado |
| Comprobar actualizaciones | Por defecto activado |
| Intervalo de comprobación | Horas entre comprobaciones. Acepta decimales. Por defecto 4 |
| Contenedores parados | Si comprueba también las actualizaciones de los contenedores detenidos. Por defecto activado |
| Por contenedor | Qué 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 notificaciones | Canal 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 Docker | Las 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ónimas | Una 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.
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.
Hay dos formas, y para la mayoría de la gente la primera es la respuesta:
| Forma | Qué necesita | Cuándo |
|---|---|---|
ssh://usuario@maquina | Nada en el host remoto salvo su sshd de siempre | La recomendada. Si ya entras por ssh a esa máquina, ya está medio hecho |
tcp://maquina:2375 | Un socket proxy en la máquina remota | Si 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 conssh://disponible no le veo la necesidad, pero si tu caso lo pide está explicado en la FAQ, en «Quiero usartcp://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.
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.
Por defecto, cuando hay una versión nueva el bot te avisa. Para cada contenedor puedes elegir otra cosa:
/updateall./updateall.Se elige desde el bot, de dos formas, y en las dos cada toque pasa al siguiente (avisar → actualizar solo → no comprobar):
/info de un contenedor, con el botón 🤖 - Versión nueva./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…».
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:
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.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.
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:
/settings → Estadísticas anónimas. Al desactivarlas se borra también el identificador de la instalación.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: 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.
Las preguntas frecuentes (versiones de las imágenes, labels, varios hosts, tcp:// con TLS...) están en GitHub.
Content type
Image
Digest
sha256:2678c5378…
Size
35.5 MB
Last updated
8 days ago
docker pull dgongut/docker-controller-bot