luall0/dockergram repository overview

⁠DockerGram

A Telegram bot for managing Docker containers via docker.sock.

Designed for individual use - Perfect for managing personal home servers, remote development environments, or homelab setups. While it can technically be used in enterprise contexts, managing company service stacks through Telegram is not recommended for production environments.

⁠Features

• 🐳 Manage Docker containers through Telegram
• 🔧 Configurable command prefix (default: /dg)
• 🔐 User authentication via Telegram user IDs
• 🔌 Direct access to Docker daemon via socket
• 📊 Real-time container resource monitoring (CPU, memory, network, disk I/O)
• 📝 View container logs with configurable line count
• 📎 Automatic file attachment for large outputs (>4096 chars)
• 📦 Docker Compose project grouping
• 💾 Volume management with detailed inspection and pruning
• 🖼️ Image management (list, history, prune, remove)
• ▶️ Start/stop containers and projects with dependency handling
• 🔄 Smart container restart with network dependency detection
• 🎯 Dependency-aware compose project operations (topological sort)
• 🛡️ Self-container protection (prevents accidental bot disconnection)
• 🤖 No command conflicts with other bots
• ✅ Comprehensive test suite

⁠Available Commands

All commands require a prefix to avoid conflicts with other bots. The default prefix is /dg, but you can customize it via the COMMAND_PREFIX environment variable.

⁠Commands

Information:

• /<prefix> help - Show help message with available commands
• /<prefix> ps - List running containers
• /<prefix> all - List all containers (including stopped)
• /<prefix> status <name|id> - Get detailed container status (includes CPU/memory for running containers)
• /<prefix> log <name|id> [lines] - Get container logs (default: 50 lines)
• /<prefix> exec <name|id> <command> [args...] - Execute command in running container
• /<prefix> stats - Show resource stats for all running containers (grouped by project)
• /<prefix> stats <name|id> [<name|id> ...] - Show stats for specific container(s)
• /<prefix> stats -p <project> [<project> ...] - Show stats for compose project(s)
• /<prefix> stats --full|-f - Include network and block I/O stats

Container Control:

• /<prefix> start <name|id> [<name|id> ...] - Start one or more containers
• /<prefix> start --with-deps|-w <name|id> - Start container and its network dependents (if stopped)
• /<prefix> start --restart-deps|-r <name|id> - Start container and restart its network dependents
• /<prefix> stop <name|id> [<name|id> ...] - Stop one or more containers
• /<prefix> stop --with-deps|-w <name|id> - Stop container and its network dependents
• /<prefix> restart <name|id> - Smart restart of a container (with network dependents)

Project Control:

• /<prefix> start-project <project> [<project> ...] - Start compose project(s) in dependency order
• /<prefix> stop-project <project> [<project> ...] - Stop compose project(s) in reverse dependency order (with self-container protection)
• /<prefix> stop-project --force|-f <project> - Force stop including the bot itself
• /<prefix> restart-project <project> - Restart entire Docker Compose project (dependency-aware, with self-container protection)
• /<prefix> restart-project --force|-f <project> - Force restart including the bot itself

Volume Management:

• /<prefix> volume ls [--detailed|-d] - List all Docker volumes (with optional container usage)
• /<prefix> volume <name> - Inspect a specific volume with container details
• /<prefix> volume prune [--all|-a] - Remove unused volumes (anonymous only, or all with --all)

Image Management:

• /<prefix> image ls - List all Docker images with repository, tag, ID, creation date, and size
• /<prefix> image history <name|id> - Show image layer history
• /<prefix> image prune [--all|-a] - Remove unused images (dangling only, or all with --all)
• /<prefix> image rm <name|id> [<name|id> ...] - Delete specific image(s) not in use

⁠Examples (with default prefix /dg)

/dg help                         # Show help message
/dg ps                           # Quick list of running containers
/dg all                          # List all containers
/dg status nginx                 # Get status of container named "nginx"
/dg log nginx 100                # Get last 100 lines of logs
/dg exec nginx ls -la            # Execute command in container
/dg stats                        # Show stats for all running containers
/dg stats nginx                  # Show stats for single container
/dg stats -p myapp               # Show stats for entire project
/dg stats --full                 # Show stats with network & block I/O

# Container control
/dg start nginx                  # Start single container
/dg start --with-deps gluetun    # Start gluetun and any stopped dependents
/dg start -r gluetun             # Start gluetun and restart running dependents
/dg stop nginx app               # Stop multiple containers
/dg restart app                  # Restart with auto-detection of network dependents

# Project control
/dg start-project myapp          # Start all containers in myapp project
/dg stop-project myapp           # Stop containers (skips bot if it's in the project)
/dg stop-project --force myapp   # Force stop including bot itself
/dg restart-project myapp        # Restart entire project (skips bot if it's in the project)

# Volume management
/dg volume ls                    # List all volumes (compact view)
/dg volume ls --detailed         # List volumes with container usage details
/dg volume my-volume             # Inspect specific volume with container details
/dg volume prune                 # Remove unused anonymous volumes only
/dg volume prune --all           # Remove ALL unused volumes (including named)

# Image management
/dg image ls                     # List all images
/dg image history nginx:latest   # Show layer history for nginx image
/dg image prune                  # Remove dangling images only
/dg image prune --all            # Remove ALL unused images
/dg image rm nginx:old           # Remove specific image

⁠Quick Start with Docker

⁠Prerequisites

• Docker daemon running
• Telegram Bot Token (from @BotFather⁠)
• Your Telegram User ID (send /start to @userinfobot⁠)

⁠Using Docker Run

docker run -d \
  --name dockergram \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e TELEGRAM_BOT_TOKEN=your_bot_token_here \
  -e ALLOWED_USER_IDS=123456789 \
  -e COMMAND_PREFIX=dg \
  luall0/dockergram:latest

⁠Using Docker Compose

Create a docker-compose.yml:

services:
  dockergram:
    image: luall0/dockergram:latest
    container_name: dockergram
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      TELEGRAM_BOT_TOKEN: your_bot_token_here
      ALLOWED_USER_IDS: 123456789,987654321     # Comma-separated for multiple users
      COMMAND_PREFIX: dg                         # Optional, defaults to 'dg'
      DOCKER_SOCKET_PATH: /var/run/docker.sock   # Optional, defaults to this path
      ALLOW_SELF_RESTART: false                  # Optional, prevents accidental bot disconnection
    healthcheck:
      test: ["CMD", "node", "dist/healthcheck.js"]
      interval: 30s
      timeout: 5s
      start_period: 10s
      retries: 3

Start the bot:

docker compose up -d

⁠Environment Variables

• TELEGRAM_BOT_TOKEN (required): Your Telegram bot token from BotFather
• ALLOWED_USER_IDS (required): Comma-separated list of authorized Telegram user IDs
• COMMAND_PREFIX (optional): Command prefix for bot commands (default: dg)
• DOCKER_SOCKET_PATH (optional): Path to Docker socket (default: /var/run/docker.sock)
• ALLOW_SELF_RESTART (optional): Allow project commands to stop/restart the bot (default: false)

⁠Health Check

The Docker image includes a built-in health check that verifies:

• Docker daemon connectivity (via docker.ping())
• Telegram API connectivity (via bot.telegram.getMe())

The health check runs every 30 seconds and marks the container as unhealthy if either check fails. This allows Docker Compose or orchestration tools to automatically restart the container if connectivity is lost.

⁠Security

This bot requires access to the Docker socket, which provides full control over Docker. Ensure you:

• Configure ALLOWED_USER_IDS to restrict access
• Never expose your bot token
• Run with appropriate permissions
• Review and understand the security implications

⁠Special Thanks

Big shoutout to Claude Code⁠ and Anthropic⁠ for building such an incredible tool that empowers developers and makes building projects like this so much more efficient and enjoyable.

⁠License

Apache 2.0

For full documentation, examples, and source code, visit: https://github.com/luall0/dockergram⁠