ragnarok22/telegram-bot-api-docker repository overview

⁠Telegram Bot API Dockerized

Dockerized Telegram Bot API⁠ server with a minimal Alpine runtime image and a configurable entrypoint.

⁠Table of Contents

• Quick Start⁠
• Docker Compose⁠
• Environment Variables⁠
• Usage⁠
• Apple Silicon and ARM64⁠
• Development⁠
• CI/CD and Release⁠
• Troubleshooting⁠
• Switching from api.telegram.org⁠
• Moving Between Local Servers⁠
• Documentation⁠
• License⁠

⁠Quick Start

1. Install Docker⁠.
2. Pull the image:

   docker pull ragnarok22/telegram-bot-api-docker
   

   Copy
3. Create .env:

   TELEGRAM_API_ID=12345
   TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef
   # Optional overrides:
   # TELEGRAM_HTTP_PORT=8081
   # TELEGRAM_HTTP_STAT_PORT=8082
   # TELEGRAM_DIR=/data
   # TELEGRAM_TEMP_DIR=/tmp
   # TELEGRAM_LOG_FILE=/data/logs/telegram-bot-api.log
   # TELEGRAM_LOCAL=true
   # TELEGRAM_EXTRA_ARGS=--max-webhook-connections 80
   

   Copy
   Get credentials from https://my.telegram.org⁠.
4. Start the container:

   docker run -d --name telegram-bot-api \
     --env-file .env \
     -p 8081:8081 -p 8082:8082 \
     -v "$(pwd)/data:/data" \
     ragnarok22/telegram-bot-api-docker
   

   Copy
5. Verify:

   curl http://localhost:8081/bot<TOKEN>/getMe
   

   Copy

The default log file is /data/logs/telegram-bot-api.log inside the container.

⁠Docker Compose

This repository includes compose.yml⁠, which builds from the local Dockerfile:

docker compose up -d --build

Compose service details:

• service name: telegram-api
• ports: 8081 (API), 8082 (statistics)
• mounted volume: ./data:/data
• env file: .env

If you prefer using the published image directly, use this minimal compose snippet:

services:
  telegram-bot-api:
    image: ragnarok22/telegram-bot-api-docker
    env_file: .env
    ports:
      - "8081:8081"
      - "8082:8082"
    volumes:
      - ./data:/data

⁠Environment Variables

⁠Usage

Run with defaults:

docker run -d --env-file .env -p 8081:8081 -p 8082:8082 ragnarok22/telegram-bot-api-docker

Run with custom ports and local mode:

docker run -d --env-file .env \
  -e TELEGRAM_HTTP_PORT=9000 \
  -e TELEGRAM_HTTP_STAT_PORT=9001 \
  -e TELEGRAM_LOCAL=true \
  -p 9000:9000 -p 9001:9001 \
  ragnarok22/telegram-bot-api-docker

Pass through additional upstream flags:

docker run -d --env-file .env \
  -e TELEGRAM_EXTRA_ARGS="--max-webhook-connections 50 --log-verbosity-level 3" \
  -p 8081:8081 -p 8082:8082 \
  ragnarok22/telegram-bot-api-docker

Bypass default startup logic and execute a custom command:

docker run --rm ragnarok22/telegram-bot-api-docker ./telegram-bot-api --version

⁠Apple Silicon and ARM64

The image is multi-arch (linux/amd64, linux/arm64), so Docker usually picks the correct variant automatically.

Build locally on Apple Silicon:

docker build -t telegram-bot-api:dev .

If you need to force a platform at runtime:

docker run --rm --platform linux/arm64/v8 ragnarok22/telegram-bot-api-docker ./telegram-bot-api --version

⁠Development

• Build local image: docker build -t telegram-bot-api:dev .
• Run entrypoint tests: bash tests/run.sh
• Run compose stack from source: docker compose up -d --build

The Dockerfile pins the upstream Telegram Bot API commit for reproducible builds. To test another revision, pass --build-arg TELEGRAM_BOT_API_COMMIT=<commit> to docker build.

⁠CI/CD and Release

GitHub Actions workflows:

• test: runs bash tests/run.sh on push/PR to main.
• docker-smoke: reusable/manual workflow for Docker build and smoke checks.
• docker-release: runs on pushed tags matching v*.*, then builds and pushes multi-arch images.

Release examples that match the current workflow trigger:

• v10.3
• v10.3.0

Publishing requires repository secrets:

• DOCKERHUB_USERNAME
• DOCKERHUB_TOKEN

⁠Troubleshooting

• Missing credentials:
  • ensure TELEGRAM_API_ID and TELEGRAM_API_HASH are present in .env.
• Permission issues with host volume:
  • create ./data before first run and ensure it is writable.
• Port conflicts:
  • change TELEGRAM_HTTP_PORT and/or TELEGRAM_HTTP_STAT_PORT and map matching host ports.
• API call failures:
  • check container logs and /data/logs/telegram-bot-api.log.

Security note:

• TELEGRAM_LOCAL allows serving local files and should be enabled only in trusted environments with proper network isolation.

⁠Switching from api.telegram.org

To guarantee that your bot receives all updates, first deregister it from https://api.telegram.org by calling logOut⁠.

After logout, point your bot client to your local server address. If launched with --local, ensure your bot can handle absolute file paths in getFile responses.

⁠Moving Between Local Servers

If the same bot is logged in on multiple servers, update delivery is not guaranteed.

To move safely:

1. Call logOut⁠ on the old server.
2. Optionally call deleteWebhook⁠, then close⁠ to reduce update loss during migration.
3. Move the bot subdirectory (named by bot user ID) from the old server's working directory to the new server's working directory.

⁠Documentation

• Telegram Bots introduction⁠
• Telegram Bot API reference⁠
• Telegram Bot API build instructions generator⁠
• @BotNews⁠ and @BotTalk⁠ for updates and discussion

⁠License

Telegram Bot API server source code is licensed under the Boost Software License. See LICENSE⁠ for details.