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

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

   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

5. Verify:

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

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

Variable	Required	Default	Description
TELEGRAM_API_ID	Yes	-	API ID from https://my.telegram.org
TELEGRAM_API_HASH	Yes	-	API hash from https://my.telegram.org
TELEGRAM_HTTP_PORT	No	8081	HTTP API listen port
TELEGRAM_HTTP_STAT_PORT	No	8082	HTTP statistics port
TELEGRAM_DIR	No	/data	Bot data directory
TELEGRAM_TEMP_DIR	No	/tmp	Temp directory for HTTP files
TELEGRAM_LOG_FILE	No	/data/logs/telegram-bot-api.log	Log file path
TELEGRAM_LOCAL	No	disabled	Enable --local mode with 1 or true
TELEGRAM_EXTRA_ARGS	No	empty	Extra flags passed verbatim to telegram-bot-api

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

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.1
• v10.1.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.