• 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.

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

• ✅ 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
• ✅ 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
• ✅ 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)

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.

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).

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.

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

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.

Cómo conectar con un host remoto

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

⚠️ 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 prueba que lo decide

Antes de configurar nada en el bot, comprueba desde una terminal de la máquina donde corre el bot:

ssh usuario@maquina docker version

Si eso te devuelve las versiones de cliente y servidor, ssh://usuario@maquina va a funcionar. Si falla, el mensaje te dice exactamente qué arreglar y no hace falta tocar el bot para nada.

El motivo es que el bot no habla un protocolo propio: abre una sesión ssh y ejecuta docker system dial-stdio en la máquina remota. Así que lo único que hace falta allí es que el usuario tenga el binario docker en su PATH y permiso sobre el socket.

ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519

ssh-copy-id -i ~/.ssh/id_ed25519.pub usuario@maquina

ssh-copy-id -i ~/.ssh/id_ed25519.pub root@unraid
ssh-copy-id -i ~/.ssh/id_ed25519.pub admin@synology

ssh usuario@maquina docker version

sudo usermod -aG docker usuario   # y vuelve a entrar por ssh

volumes:
    - /var/run/docker.sock:/var/run/docker.sock # NO CAMBIAR
    - /ruta/para/guardar/la/configuracion:/app/config
    - ~/.ssh:/root/.ssh:ro # Solo si vas a usar hosts ssh://

nas ssh://usuario@nas

ssh root@unraid docker version
ssh admin@synology docker version

ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_unraid   -C "dcb-unraid"
ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_synology -C "dcb-synology"

ssh-copy-id -i ~/.ssh/id_unraid.pub   root@unraid
ssh-copy-id -i ~/.ssh/id_synology.pub admin@synology

Host unraid
    HostName unraid.lan
    User root
    IdentityFile ~/.ssh/id_unraid

Host synology
    HostName 192.168.1.20
    User admin
    Port 2222
    IdentityFile ~/.ssh/id_synology

services:
    docker-socket-proxy:
        image: tecnativa/docker-socket-proxy
        container_name: docker-socket-proxy
        environment:
            - CONTAINERS=1
            - IMAGES=1
            - NETWORKS=1
            - VOLUMES=1
            - POST=1 # necesario para arrancar, parar y actualizar
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock:ro
        ports:
            - 2375:2375
        labels:
            - "DCB-Ignore-Check-Updates" # El bot llega a esta máquina A TRAVÉS del proxy no debe actualizarlo
        restart: unless-stopped

docker -H tcp://maquina:2375 version

ssh root@unraid docker version

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.

• Añadiendo la etiqueta DCB-Ignore-Check-Updates a un contenedor, no se comprobarán actualizaciones para él.
• Añadiendo la etiqueta DCB-Auto-Update a un contenedor, se actualizará automáticamente sin preguntar.

Ver ejemplo completo en la FAQ: «He visto que se pueden añadir labels…».

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.

Sí, siempre que la imagen lo diga. El aviso de actualización, la lista de /updateall, la comparativa antes de confirmar y el resumen final muestran el salto de versión, por ejemplo 1.43.3 → 1.43.4. /info también enseña la versión de cada contenedor y la actualización pendiente.

De dónde la saca. No del tag, porque latest puede apuntar a cualquier cosa, sino de la propia imagen y sin peticiones extra:

• La etiqueta estándar org.opencontainers.image.version (o la antigua org.label-schema.version), que llevan la mayoría de imágenes modernas, como las de linuxserver.
• En las imágenes oficiales de Docker (nginx, postgres, redis…), que no llevan esa etiqueta, su variable de entorno con la versión: NGINX_VERSION, PG_VERSION…

Si la imagen no declara su versión, la actualización se detecta igual, porque el bot compara la imagen local con la del registro, pero no puede ponerle números: verás la fecha y el identificador (digest) de cada imagen.

Además:

• Si sube el primer número (1.x → 2.0), la comparativa avisa de que puede traer cambios incompatibles. Las versiones con fecha, como 2026.10.1, no cuentan como salto mayor.
• Si la imagen indica su repositorio de GitHub (etiqueta org.opencontainers.image.source), la comparativa enlaza a las novedades de esa versión, o a la lista de versiones si no encuentra su página.

Efectivamente, actualmente hay dos etiquetas (labels) que puedes añadir a los contenedores para controlarlos:

• DCB-Ignore-Check-Updates
• DCB-Auto-Update

Para añadirlas a un contenedor, basta con editar el archivo docker-compose.yml y agregarlas bajo la clave labels.
A continuación se muestra un ejemplo con Home Assistant:

services:
  homeassistant:
    image: lscr.io/linuxserver/homeassistant:latest
    container_name: homeassistant
    network_mode: host
    environment:
      - PUID=1026
      - PGID=100
      - TZ=Etc/Madrid
    volumes:
      - /volume2/docker/homeassistant/config:/config
      - /volume2/temp/ha:/tmp
    labels:
      - "DCB-Auto-Update"
    restart: unless-stopped

Sí. Cuando entras en un proyecto verás cada contenedor por separado con su estado y podrás actuar sobre él individualmente, igual que sobre los contenedores standalone.

Las acciones globales (arrancar, parar, reiniciar o eliminar el proyecto entero) están disponibles como un botón adicional dentro del menú del proyecto.

No. Cuando se define ese canal, los avisos de cambio de estado de los contenedores (arranque, parada, caída y actualizaciones automáticas) van solo a ese canal y dejan de aparecer en el chat principal.

El resto de mensajes (resultados de comandos, menús interactivos, avisos de actualización disponible con sus botones, etc.) nunca van a ese canal: el bot siempre responde en el sitio desde el que le hablas, sea el chat privado o el grupo/tema configurado en TELEGRAM_GROUP y TELEGRAM_THREAD.

El bot te lo dice él, y solo cuando hace falta.

Con un solo host el nivel de host no aparece en ningún sitio: /list y todos los menús se ven exactamente igual que antes de que existieran los hosts. No hay nada que aprender ni nada que cambie.

En cuanto tienes dos o más, aparece donde importa: /list agrupa los contenedores por máquina con una cabecera, cada mensaje de acción dice de qué host habla, y los menús de /run, /stop, /logs… te preguntan primero el host —salvo que solo uno tenga algo que ofrecer, en cuyo caso se salta la pregunta y va directo—.

Si dos máquinas tienen un contenedor con el mismo nombre y escribes /logs nginx, el bot no adivina: te pregunta en cuál de las dos.

Entra en /settings → 🖥️ Hosts de Docker y púlsalo: la pantalla del host te dice el motivo exacto del fallo, y tienes un 🔄 Probar de nuevo para reintentar sin salir de ahí.

Lo importante es que una máquina caída no rompe el resto: /list sigue funcionando y muestra los hosts que sí responden, marcando el que no. Los comandos y las comprobaciones de actualización se saltan el que está fuera.

Para diagnosticarlo, la prueba de siempre desde la máquina del bot vale más que cualquier menú:

ssh usuario@maquina docker version

El mensaje que te dé ahí es el mismo que te está dando el bot, pero con todo el detalle. Las causas habituales están en la tabla de La prueba que lo decide (desplegable 🖥️ de arriba).

Se puede, sí, y aquí tienes el procedimiento. Pero antes lo honesto: es bastante avanzado y yo no lo considero necesario.

TLS resuelve un problema concreto: cruzar una red en la que no confías. Si tus máquinas están en tu casa, ssh:// te da exactamente la misma protección —cifrado y autenticación por clave— sin generar ni un certificado, y reutilizando el ssh que ya tienes montado. Y si necesitas llegar desde fuera, montar Tailscale o WireGuard es menos trabajo que un PKI y te sirve para todo lo demás de tu red, no solo para esto.

Dicho eso: si tu caso lo pide de verdad, o simplemente te apetece, funciona perfectamente. Ten en cuenta que es el único camino que no se puede añadir desde el bot y hay que escribir el host a mano en settings.json, como se ve en el paso 5.

Todo lo de abajo va en la máquina remota, salvo donde diga lo contrario.

1. Genera la CA y los certificados. Sustituye maquina.local por el nombre o IP con el que el bot va a llamarla:

openssl genrsa -aes256 -out ca-key.pem 4096
openssl req -new -x509 -days 3650 -key ca-key.pem -sha256 -out ca.pem

openssl genrsa -out server-key.pem 4096
openssl req -subj "/CN=maquina.local" -sha256 -new -key server-key.pem -out server.csr
echo "subjectAltName = DNS:maquina.local,IP:192.168.1.50" > extfile.cnf
echo "extendedKeyUsage = serverAuth" >> extfile.cnf
openssl x509 -req -days 3650 -sha256 -in server.csr -CA ca.pem -CAkey ca-key.pem   -CAcreateserial -out server-cert.pem -extfile extfile.cnf

openssl genrsa -out key.pem 4096
openssl req -subj "/CN=client" -new -key key.pem -out client.csr
echo "extendedKeyUsage = clientAuth" > extfile-client.cnf
openssl x509 -req -days 3650 -sha256 -in client.csr -CA ca.pem -CAkey ca-key.pem   -CAcreateserial -out cert.pem -extfile extfile-client.cnf

2. Configura el daemon en /etc/docker/daemon.json:

{
  "tlsverify": true,
  "tlscacert": "/etc/docker/certs/ca.pem",
  "tlscert": "/etc/docker/certs/server-cert.pem",
  "tlskey": "/etc/docker/certs/server-key.pem",
  "hosts": ["unix:///var/run/docker.sock", "tcp://0.0.0.0:2376"]
}

En systemd hay que quitar el -H que trae la unidad, o dockerd se queja de que el host está definido dos veces:

sudo mkdir -p /etc/systemd/system/docker.service.d
printf '[Service]
ExecStart=
ExecStart=/usr/bin/dockerd
' |   sudo tee /etc/systemd/system/docker.service.d/override.conf
sudo systemctl daemon-reload && sudo systemctl restart docker

3. Copia ca.pem, cert.pem y key.pem a la máquina del bot y mapéalos:

volumes:
    - /ruta/a/los/certs:/certs:ro

4. Comprueba antes de configurar el bot:

docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem   -H tcp://maquina.local:2376 version

5. Declara el host a mano. Esta es la única vía que no se puede añadir desde /settings: la pantalla de añadir host solo pide una URL, y un host con TLS necesita además las rutas de los tres certificados. Se escribe en settings.json, dentro del volumen que mapeaste, en la lista hosts:

{
    "id": "h_tls1",
    "alias": "maquina",
    "url": "tcp://maquina.local:2376",
    "local": false,
    "tls": {
        "ca": "/certs/ca.pem",
        "cert": "/certs/cert.pem",
        "key": "/certs/key.pem",
        "verify": true
    }
}

Las rutas son las de dentro del contenedor, o sea la parte derecha del volumen del paso 3. El id lo eliges tú y da igual cuál sea, siempre que no se repita: solo tiene que ser estable, porque es lo que atan las programaciones y la caché de actualizaciones.

❗ Importante: editar settings.json a mano requiere reiniciar el contenedor: el bot lo lee al arrancar y lo mantiene en memoria. Después del reinicio el host aparece en /settings → 🖥️ Hosts de Docker como cualquier otro, y ya se puede probar, renombrar y quitar desde ahí.

Desde el chat privado con el bot y desde el grupo (o el tema concreto del supergrupo) que hayas configurado en TELEGRAM_GROUP y TELEGRAM_THREAD.

El bot contesta siempre donde le has escrito: si lanzas /list en el privado, la lista aparece en el privado; si lo lanzas en el tema del grupo, aparece en ese tema. El canal de notificaciones solo recibe las alertas de cambio de estado.

Cualquier otro chat se ignora: si el bot está metido en otro grupo, ahí no responde ni ejecuta nada, aunque quien escriba sea administrador. Ser administrador no basta, el chat también tiene que ser el privado del propio administrador o TELEGRAM_GROUP.

Igual que cualquier otro contenedor: desde /checkupdate docker-controller-bot o desde /updateall.

Internamente el bot lanza un contenedor auxiliar (UPDATER-Docker-Controler-Bot) que se encarga de descargar la nueva imagen, sustituirla y volver a levantar el bot, evitando que el propio bot se quede sin proceso a mitad de la actualización.

Si le añades la label DCB-Auto-Update a su docker-compose.yml, se actualizará solo en cuanto detecte una nueva versión.

Ejecución con código local

Para su ejecución en local y probar nuevos cambios de código, se necesita renombrar el fichero .env-example a .env con los valores necesarios para su ejecución. Es necesario establecer un TELEGRAM_TOKEN y un TELEGRAM_ADMIN correctos y diferentes al de la ejecución normal.

La estructura de carpetas debe quedar:

docker-controller-bot/
    ├── .env
    ├── .gitignore
    ├── LICENSE
    ├── requirements.txt
    ├── README.md
    ├── Dockerfile_local
    ├── docker-compose.debug.yaml
    ├── docker-controller-bot.py   # punto de entrada: importa y arranca
    ├── core.py                    # el núcleo: DockerManager, monitores, teclados, UI
    ├── commands.py                # un `cmd_*` por comando
    ├── callbacks.py               # un `cb_*` por botón
    ├── callback_registry.py       # el decorador `@callback` y el parseo
    ├── host_registry.py           # los hosts Docker y su caché de clientes
    ├── store.py                   # settings.json, estado y cachés
    ├── migration.py               # migraciones de arranque (4.x → 5.0)
    ├── config.py                  # variables de arranque y constantes
    ├── i18n.py                    # carga de idiomas y `get_text`
    ├── own_container.py           # se identifica a sí mismo sin que se lo digan
    ├── docker_update.py
    ├── docker_compose_manager.py
    ├── compose_generator.py
    ├── port_manager.py
    ├── schedule_manager.py
    ├── message_queue.py
    ├── logger.py
    ├── tests
    │   ├── run_all.py
    │   └── ...
    └── locale
        ├── en.json
        ├── es.json
        ├── de.json
        ├── ru.json
        ├── gl.json
        ├── nl.json
        ├── cat.json
        └── it.json

Para levantarlo habría que ejecutar en esa ruta: docker compose -f docker-compose.debug.yaml up -d --build --force-recreate Para detenerlo y eliminarlo: docker compose down --rmi

Para probar nuevos cambios bastaría con guardar. Los cambios se refrescan en caliente.

Los tests

python3 tests/run_all.py

No necesitan Docker: el SDK va sustituido y los ajustes se escriben en un directorio temporal, así que se pueden lanzar en cualquier sitio. Pasan un rato comprobando cosas que solo se ven en tiempo de ejecución —nombres que un módulo no define, claves de idioma que nada renderiza, botones que llevarían un id sin su host, marcado que se ha ido de un idioma— así que si tocas código, lánzalos antes de proponer el cambio.

Se puede filtrar por módulo: python3 tests/run_all.py test_hosts.

Depuración con VS Code

Abre la carpeta del repositorio en Visual Studio Code necesitaras las siguientes extensiones instaladas en VS Code:

• Docker
• Python

Instalación de las extensiones

1. Abre VS Code.
2. Ve a la extensión de la barra lateral y busca "Docker" y "Python".
3. Instala ambas extensiones desde el Marketplace.

Establecer Puntos de Parada (Breakpoints)

1. Abre el archivo de código que deseas depurar.
2. Haz clic en el margen izquierdo junto a la línea de código donde quieras establecer un punto de parada. Aparecerá un punto rojo indicando el breakpoint.

Iniciar la Depuración

1. Ve al menú Run y selecciona Start Debugging o presiona F5.
2. VS Code arrancará el docker-compose.debug.yaml y comenzará la depuración.
3. La ventana de depuración se abrirá en la parte inferior, mostrando las variables, la pila de llamadas y la consola de depuración.

Conclusión de la Depuración

• Para detener la sesión de depuración, ve a Run > Stop Debugging o presiona Shift+F5