Docker-Controller-Bot

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

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

• ✅ Listar contenedores
• ✅ Arrancar, parar y eliminar 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
• ✅ 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)

¿Lo buscas en ?

NUEVO Canal de novedades en

Crear tu bot de Telegram

Antes de levantar el contenedor necesitas un bot propio en Telegram y conocer tu identificador de usuario.

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.

Comandos disponibles

Casi todos los comandos pueden ejecutarse en dos modos: escribiendo el comando solo (/run) para que el bot muestre un menú interactivo con botones, o pasando directamente el nombre del contenedor (/run nginx) para actuar sin menús.

Soporte para Docker Compose

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. Las acciones de inicio, parada, reinicio y borrado se pueden aplicar al proyecto entero o a un contenedor individual.

Programaciones (/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.
• Las programaciones se persisten en /app/schedule (recuerda mapear ese volumen).

Configuración en las variables del Docker Compose

Anotaciones

Ejemplo de Docker-Compose para su ejecución normal

services:
    docker-controller-bot:
        environment:
            - TELEGRAM_TOKEN=
            - TELEGRAM_ADMIN=
            - CONTAINER_NAME=docker-controller-bot
            - TZ=Europe/Madrid
            #- TELEGRAM_GROUP=
            #- TELEGRAM_THREAD=1
            #- TELEGRAM_NOTIFICATION_CHANNEL=
            #- CHECK_UPDATES=1
            #- CHECK_UPDATE_EVERY_HOURS=4
            #- CHECK_UPDATE_STOPPED_CONTAINERS=1
            #- BUTTON_COLUMNS=2
            #- LANGUAGE=ES
            #- EXTENDED_MESSAGES=0
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock # NO CAMBIAR
            - /ruta/para/guardar/las/programaciones:/app/schedule # CAMBIAR LA PARTE IZQUIERDA
            #- ~/.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
        tty: true

Funciones Extra mediante Labels/Etiquetas en otros contenedores

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

Agradecimientos

• Traducción al neerlandés: ManCaveMedia
• Traducción al alemán: shedowe19
• Traducción al ruso: leyalton
• Traducción al gallego: monfero
• Traducción al italiano: zichichi
• Traducción al catalán: flancky
• Pruebas del Docker Login: garanda
• Readme en inglés: phampyk

❓ Preguntas Frecuentes (FAQ)

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

Solo para desarrolladores

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
    ├── config.py
    ├── docker-controller-bot.py
    ├── Dockerfile_local
    ├── docker-compose.yaml
    └── 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.

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