remotecellist/dockalert-telegram repository overview

⁠Dockalert-Telegram: Docker Container Monitor with Web UI & Telegram Alerts

Image: remotecellist/dockalert-telegram:latest (or replace latest with a specific version tag like 1.1.0)

Dockalert-Telegram is a self-hosted application that monitors your Docker container events and sends real-time notifications via Telegram. It includes a web-based UI to view container statuses, manage which containers are monitored, view logs, and configure application settings.

⁠Features

• Web UI:
  • View status of all Docker containers (running, exited, etc.).
  • Select specific containers to monitor for unexpected exits.
  • View recent logs for individual containers.
  • Change application password.
  • Customize the number of containers displayed per page (10, 25, 50, 100, All).
  • Secure login for accessing the UI.
• Telegram Notifications:
  • Receive immediate alerts when a monitored container exits unexpectedly.
  • Alerts include container name, exit code, and a description of the exit code.
• Docker Event Monitoring:
  • Continuously listens to Docker daemon events for real-time updates.
• Persistent Configuration:
  • Selections for monitored containers, display preferences, and the hashed admin password are saved in a Docker volume, persisting across restarts.
• Secure by Default:
  • Runs with a non-root user inside the containers.
  • Expects sensitive configurations via environment variables.

⁠Prerequisites for Running This Image

• Docker Engine: Ensure Docker is installed and running on your host system.
• Docker Compose (Recommended): Simplifies multi-service application management.
• Telegram Bot Token: You'll need to create a Telegram Bot and get its API Token.
  1. Talk to @BotFather on Telegram.
  2. Use the /newbot command.
  3. BotFather will provide you with an HTTP API Token.
• Telegram Chat ID: The ID of the chat (user, group, or channel) where your bot will send notifications.
  • If sending to yourself, message your bot, then forward one of its messages to a bot like @userinfobot to get your Chat ID.
  • For a group, add your bot to the group. Send a message like /my_id @your_bot_username in the group. Then check your bot's updates (e.g., https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates) to find the group's chat ID (it will be a negative number).
• Docker Group GID on Host: For the application to monitor Docker events, it needs access to the Docker socket.
  • On your Docker host, run: getent group docker
  • The output will be something like docker:x:GID_NUMBER:. Note the GID_NUMBER.

⁠Recommended Deployment: Using Docker Compose

This is the recommended method for a straightforward setup:

1. Create a docker-compose.yml file with the following content (replace placeholders with your actual values):

version: '3.8'

services:
  webapp:
    image: remotecellist/dockalert-telegram:latest
    container_name: dockalert-telegram-webapp
    restart: unless-stopped
    ports:
      - "5000:5000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - monitor_config_data:/config
    environment:
      - TELEGRAM_BOT_TOKEN=your_actual_telegram_bot_token_here
      - TELEGRAM_CHAT_ID=your_actual_chat_id_here
      - FLASK_SECRET=your_secret_key_here
      - FLASK_USER=admin
      - FLASK_PASSWORD=your_secure_password_here
      - FLASK_DEBUG=0
      - FLASK_RUN_PORT=5000
      - MONITORED_FILE=/config/monitored.json
      - APP_CONFIG_FILE=/config/app_config.json
      - LOG_LINES=5
    user: "1000:1000" # Replace with your Docker host's docker UID
    group_add:
      - "your_docker_host_gid_here"
    command: python -m simple_monitor.webapp

  monitor:
    image: remotecellist/dockalert-telegram:latest
    container_name: dockalert-telegram-monitor
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - monitor_config_data:/config
    environment:
      - TELEGRAM_BOT_TOKEN=your_actual_telegram_bot_token_here
      - TELEGRAM_CHAT_ID=your_actual_chat_id_here
      - MONITORED_FILE=/config/monitored.json
      - APP_CONFIG_FILE=/config/app_config.json
      - LOG_LINES=5
    user: "1000:1000" # Replace with your Docker host's docker UID
    group_add:
      - "your_docker_host_gid_here"
    command: python -m simple_monitor.monitor

volumes:
  monitor_config_data:

      APP_CONFIG_FILE: "/config/app_config.json"
      LOG_LINES: "5"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - monitor_config_data:/config
    restart: unless-stopped
    command: python -m simple_monitor.monitor

volumes:
  monitor_config_data:

1. Update the placeholders in the docker-compose.yml file:

   • your_actual_telegram_bot_token_here: Your Telegram Bot API Token
   • your_actual_chat_id_here: Your Telegram Chat ID
   • your_secret_key_here: A secure random string for the Flask application
   • your_secure_password_here: Your chosen admin password
   • your_docker_host_gid_here: The GID of the docker group on your host

2. Run the application:

   docker-compose up -d
   
   
   

   Copy

3. Access the Web UI: Open your browser to http://<your_docker_host_ip>:5000

⁠Deploying with Portainer

⁠Add Docker Hub Credentials to Portainer (Recommended):

1. In Portainer: Registries > + Add registry > Docker Hub.
2. Enter your Docker Hub username and password/access token.

⁠Deploy as a Stack:

1. In Portainer: Stacks > + Add stack.
2. Give your stack a Name (e.g., dockalert-telegram).
3. Choose Web editor.
4. Copy the docker-compose:yml content below into the editor (replace placeholders with your actual values):

version: '3.8'

services:
  webapp:
    image: remotecellist/dockalert-telegram:latest
    container_name: dockalert-telegram-webapp
    user: "1000:1000" # Replace with your Docker host's docker UID
    group_add:
      - "123"  # Replace with your Docker host's docker GID
    environment:
      TELEGRAM_BOT_TOKEN: "your_bot_token_here"
      TELEGRAM_CHAT_ID: "your_chat_id_here"
      FLASK_USER: "admin"
      FLASK_PASSWORD: "your_password_here"
      FLASK_SECRET: "your_secret_key_here"
      FLASK_DEBUG: "0"
      FLASK_RUN_PORT: "5000"
      MONITORED_FILE: "/config/monitored.json"
      APP_CONFIG_FILE: "/config/app_config.json"
      LOG_LINES: "5"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - monitor_config_data:/config
    ports:
      - "5000:5000"
    restart: unless-stopped
    command: python -m simple_monitor.webapp

  monitor:
    image: remotecellist/dockalert-telegram:latest
    container_name: dockalert-telegram-monitor
    user: "1000:1000" # Replace with your Docker host's docker UID
    group_add:
      - "123"  # Replace with your Docker host's docker GID
    environment:
      TELEGRAM_BOT_TOKEN: "your_bot_token_here"
      TELEGRAM_CHAT_ID: "your_chat_id_here"
      MONITORED_FILE: "/config/monitored.json"
      APP_CONFIG_FILE: "/config/app_config.json"
      LOG_LINES: "5"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - monitor_config_data:/config
    restart: unless-stopped
    command: python -m simple_monitor.monitor

volumes:
  monitor_config_data:

1. Click "Deploy the stack".

⁠Using the Application

• Web UI: Access via http://<your_host_ip>:5000. Log in with the username and password you configured. View container statuses, select containers to monitor, view logs, and change settings on the "Config" page.
• Telegram Notifications: The monitor service automatically sends alerts to your Telegram chat when selected containers exit unexpectedly.

⁠Troubleshooting

• Permission Denied for Docker Socket: Ensure you've entered the correct GID of the docker group on your host in the group_add section.
• Container Fails to Start: Check that all environment variables are correctly set. View the container logs with docker logs dockalert-telegram-webapp or through the Portainer interface.
• No Telegram Messages:
  • Verify your Bot Token and Chat ID are correct.
  • Ensure your bot has permission to send messages to the chat/group.
  • Check the monitor container logs for errors.
• Changed Password Not Working: The password is hashed on first login. If you need to reset it, you can remove the Docker volume and recreate the containers, or modify the app_config.json file in the volume.