Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ragnarok22/telegram-bot-api-docker/llms.txt

Use this file to discover all available pages before exploring further.

​
What is Telegram Bot API Docker?

Telegram Bot API Docker is a production-ready Docker wrapper around the official Telegram Bot API server. It packages the upstream C++ server into a minimal Alpine Linux container with a configurable entrypoint, making it simple to self-host your own Telegram Bot API instance. Instead of relying on Telegram’s public api.telegram.org endpoint, you can run your own private API server with full control over infrastructure, data storage, and configuration.

​
Why Self-Host?

Self-hosting the Telegram Bot API server provides several advantages over using the default api.telegram.org:

Larger File Uploads

Upload files up to 2000 MB instead of the 50 MB limit on the public API

Faster Downloads

Download files directly from your server without routing through Telegram’s infrastructure

Local File Access

Enable --local mode to serve files with absolute paths, perfect for media-heavy bots

Full Control

Manage your own data directory, logs, rate limits, and server configuration
Security Note: The --local mode allows serving local files and should only be enabled in trusted environments with proper network isolation.

​
Key Features

This Docker implementation includes several production-ready features:

​
Multi-Stage Build Process

The image uses a two-stage build to minimize size: 
# Stage 1: Build the upstream server from source
FROM alpine:3.23.3 AS build-stage
RUN apk add --no-cache alpine-sdk linux-headers git zlib-dev openssl-dev gperf cmake
RUN git clone --depth 1 --recurse-submodules --shallow-submodules \
      https://github.com/tdlib/telegram-bot-api.git /telegram-bot-api

# Stage 2: Minimal runtime with only necessary files
FROM alpine:3.23.3
COPY --from=build-stage /telegram-bot-api/bin/ /telegram-bot-api/bin/

​
Security Hardening

The container runs as a non-root user with minimal permissions:
  • Dedicated botapi user and group
  • Isolated data and temp directories
  • Read-only binary directory
  • Health checks for monitoring

​
Multi-Architecture Support

Built for both linux/amd64 and linux/arm64 platforms, with automatic platform detection:
  • Works seamlessly on Apple Silicon (M1/M2/M3)
  • Supports ARM64 servers and edge devices
  • No manual platform selection needed

​
Flexible Configuration

The entrypoint script (entrypoint.sh) provides environment-based configuration:
  • Required: TELEGRAM_API_ID and TELEGRAM_API_HASH
  • Optional: Ports, directories, log files, local mode, and extra arguments
  • Passthrough: Run custom commands by passing arguments directly
# Standard startup with env-based config
docker run -d --env-file .env ragnarok22/telegram-bot-api-docker

# Custom command passthrough
docker run --rm ragnarok22/telegram-bot-api-docker ./telegram-bot-api --version

​
Built-in Health Monitoring

The container includes automatic health checks: 
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD wget -qO- http://localhost:8081/ || exit 1

​
Architecture Overview

The Docker container exposes two ports:
  • 8081: HTTP API endpoint for bot operations
  • 8082: Statistics and monitoring endpoint
All bot data is stored in /data (configurable via TELEGRAM_DIR), which should be mounted as a persistent volume.

​
Use Cases

This Docker image is ideal for:
  • Media Bots: Bots that handle large files (videos, archives, backups)
  • Production Deployments: Teams that need reliable infrastructure and monitoring
  • Data Privacy: Organizations that want to control where bot data is stored
  • High-Volume Bots: Applications requiring custom rate limits or webhook configurations
  • Development Environments: Local testing with full API capabilities

​
Next Steps

Quickstart Guide

Get your server running in 5 minutes

Configuration

Learn about all environment variables and options

Docker Compose

Set up with Docker Compose for easier management

Migration Guide

Switch from api.telegram.org to your local server

​
Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us