raylabpro/telegram-bot-api repository overview

⁠telegram-bot-api

A minimal, secure, and production-oriented Docker image for telegram-bot-api — an Telegram Bot API server for creating Telegram Bots⁠.

Built as a fully static and semi static binary and shipped in a distroless runtime images, running as non-root by default.

⁠✨ Features

• 🔐 Secure by default: Distroless runtime + non-root user.
• 📦 Extended but secure variant: based on Debian and Alpine with additional network tools + non-root user.
• 🏗 Multi-arch: Supports amd64 and arm64.
• 📈 Metrics-ready: Supports metrics port (8082).

⁠⚠️ Important Notice

Telegram-bot-api is a Telegram proxy for Bot API. Operating proxies may be restricted or monitored depending on your country/ISP and may carry legal/operational risks.

You are responsible for compliance with local laws and for safe deployment (firewalling, access control, logs, monitoring).

⁠🏷️ Supported tags and respective description links

• 9.4, 9.4-distroless, distroless, latest⁠⁠
• 9.4-debian13, 9.4-debian, debian13, debian⁠⁠
• 9.4-alpine3.23, 9.4-alpine, alpine3.23, alpine⁠⁠

⁠📔 Image Variants

The telegram-bot-api images come in many flavors, each designed for a specific use case.

⁠telegram-bot-api:<version>-distroless-cc

This is the defacto image. If you are unsure about what your needs are, you probably want to use this one.

Image based on debian for build stage and gcr.io/distroless/cc:nonroot for runtime.

⁠telegram-bot-api:<version>-debian

This image is based on the Debian project⁠⁠, available in the debian official image⁠. Used Debian Linux slim tag, that is much smaller than others, and thus leads slimmer images in general.

This image contains some additional tools, like ping, telnet, curl, etc. to connectivity checks.

⁠telegram-bot-api:<version>-alpine

This image is based on the popular Alpine Linux project⁠⁠, available in the alpine official image⁠. Alpine Linux is much smaller than most distribution base images (~5MB), and thus leads to much slimmer images in general.

This variant is useful when final image size being as small as possible with additional is your primary concern. The main caveat to note is that it does use musl libc⁠⁠ instead of glibc and friends⁠⁠, so performance may be lower if depending on the depth of libc requirements/assumptions. See this Hacker News comment thread⁠⁠ for more discussion of the issues that might arise and some pro/con comparisons of using Alpine-based images.

This image contains some additional tools, like ping, telnet, curl, etc. to connectivity checks.

⁠🚀 Quick Start (Docker Compose)

⁠1. Get api_id and api_hash

Go to my.telegram.org⁠ create application if not exists and obtain App api_id and App api_hash

⁠2. Create .env with values from first step

TELEGRAM_API_ID=1234567
TELEGRAM_API_HASH=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Place your configuration file as ./.env.

⁠3. Create docker-compose.yml

---
services:
  telegram-bot-api:
    container_name: telegram-bot-api
    image: "raylabpro/telegram-bot-api:${TGBOTAPI_TAG:-distroless}"
    restart: "unless-stopped"
    pull_policy: "always"
    # network_mode: host
    ports:
      - "18081:8081"
      - "127.0.0.1:8082:8082/tcp"
    ulimits:
      nofile:
        soft: 65536
        hard: 65536

    env_file: ".env"
    environment:
      TZ: "Europe/Moscow"
      TELEGRAM_API_ID: ${TELEGRAM_API_ID}
      TELEGRAM_API_HASH: ${TELEGRAM_API_HASH}

    command:
      - --http-port=8081
      - --http-stat-port=8082
      - --data-dir=/var/lib/telegram-bot-api
      - --temp-dir=/tmp
      - --local

    volumes:
      - "/etc/timezone:/etc/timezone:ro"
      - "/etc/localtime:/etc/localtime:ro"
      - "/etc/hostname:/etc/hostname:ro"
      - "tg-data:/var/lib/telegram-bot-api"
      - "tg-logs:/var/log/telegram-bot-api"
      - "tg-tmp:/tmp"

    # Hardening
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
    # read_only: true
    # tmpfs:
    #   - /tmp:rw,nosuid,nodev,noexec,size=16m
    #   - /var/lib/telegram-bot-api:rw,nosuid,nodev,noexec,size=256m
    #   - /var/log/telegram-bot-api:rw,nosuid,nodev,noexec,size=2048m

    # Resource limits (optional)
    deploy:
      resources:
        limits:
          cpus: "0.50"
          memory: 256M

    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  tg-data:
  tg-logs:
  tg-tmp:

⁠4. Start

docker compose up -d

Logs:

docker compose logs -f

⁠⚙️ Configuration

⁠Environment Variables

⁠Shell args

⁠Volumes

⁠Ports

⁠🧠 Container Behavior

• ENTRYPOINT: /usr/local/bin/telegram-bot-api
• CMD (default): ["--local", "--http-port=8081", "--http-stat-port==8082", "--dir=/var/lib/telegram-bot-api", "--temp-dir=/tmp"]

So the container effectively runs:

/usr/local/bin/telegram-bot-api --local --http-port=8081 --http-stat-port==8082 --dir=/var/lib/telegram-bot-api --temp-dir=/tmp

To use a different arguments, override the command:

docker run ... raylabpro/telemt:latest --local --http-port=18081 --http-stat-port==28082 --dir=/var/lib/telegram-bot-api --temp-dir=/tmp