orenlab/pytmbot repository overview

⁠pyTMBot Docker Image

Secure multi-arch Docker image for pyTMBot — a Telegram bot for Docker operations, host monitoring, health checks, and optional plugins.

⁠Quick Reference

• Maintained by: OrenLab⁠
• Source code and issues: github.com/orenlab/pytmbot⁠
• Image: orenlab/pytmbot
• Supported architectures: linux/amd64, linux/arm64
• Base image: Ubuntu 24.04
• Runtime user: pytmbot (uid:gid 1001:1001)

⁠Supported Tags

Stable public tags:

Additional tags:

Recommended: use 0.3.2 for reproducible production rollouts, stable for the supported channel. Do not use edge-* tags in production.

⁠Image Features

• Non-root runtime user
• Built-in Docker HEALTHCHECK
• Multi-stage build with uv and locked Python dependencies
• OCI labels, SBOM, and provenance on release images
• Weekly base-image and OS-package refreshes for floating stable tags

⁠Security Guidance

Recommended runtime hardening:

--read-only
--security-opt no-new-privileges
--cap-drop ALL

• Docker socket access is equivalent to privileged host control. Mount /var/run/docker.sock only if you need Docker management features.
• For webhook mode, expose the app through a reverse proxy with TLS termination.

⁠Requirements

• Docker Engine 20.10+
• Docker Compose v2 recommended
• Telegram bot token from @BotFather
• A valid pytmbot.yaml configuration file

⁠Quick Start

Generate a TOTP salt:

docker run --rm orenlab/pytmbot:stable --salt

Create a config directory and download the sample config:

mkdir -p /etc/pytmbot
curl -L -o /etc/pytmbot/pytmbot.yaml \
  https://raw.githubusercontent.com/orenlab/pytmbot/master/pytmbot.yaml.sample

Minimal production run:

docker run -d \
  --name pytmbot \
  --restart on-failure \
  -e TZ=UTC \
  -e PYTMBOT_STATE_DIR=/run/pytmbot \
  -v /etc/pytmbot/pytmbot.yaml:/opt/app/pytmbot.yaml:ro \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  --read-only \
  --security-opt no-new-privileges \
  --cap-drop ALL \
  --pid host \
  --tmpfs /run/pytmbot:noexec,nosuid,nodev,size=10m,uid=1001,gid=1001 \
  orenlab/pytmbot:stable --mode prod

For pinned rollouts, replace stable with 0.3.2. To enforce Docker socket availability on startup, add -e STRICT_DOCKER_ACCESS=True.

⁠Docker Compose Example

services:
  pytmbot:
    image: orenlab/pytmbot:stable
    container_name: pytmbot
    restart: on-failure
    environment:
      TZ: UTC
      PYTMBOT_STATE_DIR: /run/pytmbot
    volumes:
      - /etc/pytmbot/pytmbot.yaml:/opt/app/pytmbot.yaml:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
    security_opt:
      - no-new-privileges:true
    read_only: true
    cap_drop:
      - ALL
    pid: host
    tmpfs:
      - /run/pytmbot:noexec,nosuid,nodev,size=10m,uid=1001,gid=1001
      - /tmp:noexec,nosuid,nodev,size=100m,uid=1001,gid=1001
      - /var/tmp:noexec,nosuid,nodev,size=50m,uid=1001,gid=1001
    command: [ "--mode", "prod" ]

⁠Configuration Overview

Required top-level sections in pytmbot.yaml:

Optional sections: webhook_config, plugins_config, influxdb.

Notes:

• plugins_config.monitor also requires the top-level influxdb section.
• Webhook mode requires a valid webhook_config.

⁠Runtime Flags

Examples:

# Verify Docker socket access
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  orenlab/pytmbot:stable --check-docker

# Run with plugins
docker run -d \
  --name pytmbot \
  -v /etc/pytmbot/pytmbot.yaml:/opt/app/pytmbot.yaml:ro \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  orenlab/pytmbot:stable --mode prod --plugins monitor outline

⁠Webhook Notes

• Polling is the simplest deployment mode — no public endpoint required.
• Webhook mode should be placed behind a reverse proxy with TLS termination.
• Use --socket_host 0.0.0.0 for containerized webhook listeners.
• webhook_config.local_port must be >= 1024.

⁠Upgrade Policy

• Exact release tags (0.3.2) are immutable.
• Floating tags (0.3, stable, latest) can move forward.
• Weekly rebuilds refresh the Ubuntu base image and installed OS packages.
• Python dependency updates require a committed uv.lock change and a new release.

⁠Documentation

• Project repository⁠
• Runtime documentation⁠
• Settings reference⁠
• CLI reference⁠
• Release policy⁠

⁠License

Released under the MIT License⁠.