Upstream Project

Information about the upstream Telegram Bot API server and official resources

This Docker image wraps the official Telegram Bot API server. Understanding the upstream project helps you leverage its full capabilities and report issues to the right place.

Upstream Repository

telegram-bot-api

Official Telegram Bot API server source code maintained by the Telegram team

The upstream project is the official C++ implementation of the Telegram Bot API server that this Docker image builds and runs.

About the Upstream Server

• Language: C++ (built on TDLib)
• Maintainer: Telegram team
• License: Boost Software License 1.0
• Repository: https://github.com/tdlib/telegram-bot-api

Build Process

This Docker image compiles the upstream server from source:

# Multi-stage build
FROM alpine:3.23.3 AS build-stage

RUN apk add --no-cache alpine-sdk linux-headers git \
    zlib-dev openssl-dev gperf cmake

# Clone upstream repository
RUN git clone --depth 1 \
      --recurse-submodules --shallow-submodules \
      https://github.com/tdlib/telegram-bot-api.git

# Build with CMake
RUN cd telegram-bot-api/build && \
    cmake -DCMAKE_BUILD_TYPE=Release .. && \
    cmake --build . --target install

The image tracks the default branch of the upstream repository. Each release is tagged with the corresponding upstream version.

Version Alignment

This Docker image versions align with upstream Telegram Bot API releases:

Docker Image Tag	Upstream Version	Release Date
latest	Latest default branch	Rolling
9.5	9.5	2024
9.5.0	9.5.0	2024

Check your running version:

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

Official Documentation

Telegram Bots Introduction

Getting started guide for Telegram bot developers

Bot API Reference

Complete API reference for all bot methods and types

Build Instructions

Interactive build instructions generator for the upstream server

TDLib Documentation

Documentation for the underlying TDLib library

Telegram Resources

Official Channels

@BotNews

Official channel for Bot API updates and announcements

@BotTalk

Community discussion group for bot developers

Getting Your Credentials

To use the Telegram Bot API server, you need credentials from Telegram:

1. Visit https://my.telegram.org
2. Log in with your phone number
3. Go to “API development tools”
4. Create an application to get:
   • api_id (set as TELEGRAM_API_ID)
   • api_hash (set as TELEGRAM_API_HASH)

Keep your api_id and api_hash secret. Never commit them to version control or share them publicly.

Reporting Issues

Where to Report

Determine the right place to report issues:

Report to this Docker project if the issue is related to:

• Docker image build failures
• Entrypoint script bugs
• Environment variable handling
• Container startup issues
• Multi-architecture support
• Documentation errors

Docker Project Issues

Report Docker-specific issues here

Report to upstream if the issue is related to:

• Telegram Bot API server functionality
• API method behavior
• Webhook handling
• File upload/download
• TDLib errors
• Bot API specification compliance

Upstream Issues

Report upstream server issues here

Before Reporting

1. Search existing issues to avoid duplicates
2. Test with latest version to ensure it’s not already fixed
3. Gather information:
   • Docker version and platform (amd64/arm64)
   • Container logs
   • Environment variables (redact secrets)
   • Steps to reproduce

License Information

Upstream License

The Telegram Bot API server is licensed under the Boost Software License 1.0:

Boost Software License

Official license text for the upstream Telegram Bot API server

Key points:

• Free for commercial and non-commercial use
• No restrictions on distribution
• No warranty provided

Docker Wrapper License

This Docker wrapper (Dockerfile, entrypoint script, documentation) maintains compatibility with the upstream license.

Contributing

Contributing to This Project

Contributions to the Docker wrapper are welcome:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: bash tests/run.sh
5. Submit a pull request

Areas for contribution:

• Improved documentation
• Additional environment variable support
• Enhanced testing
• Bug fixes
• Security improvements

Contributing Upstream

To contribute to the Telegram Bot API server itself:

1. Review upstream contribution guidelines
2. Ensure your changes align with Telegram’s API specification
3. Submit pull requests to the upstream repository

Advanced: Building from Source

If you want to build the upstream server manually (without Docker):

Build Instructions Generator

Interactive tool that generates platform-specific build instructions

Build Dependencies

Alpine Linux:

apk add alpine-sdk linux-headers git zlib-dev openssl-dev gperf cmake

Ubuntu/Debian:

apt-get install make git zlib1g-dev libssl-dev gperf cmake g++

Build commands:

git clone --recurse-submodules https://github.com/tdlib/telegram-bot-api.git
cd telegram-bot-api
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --target install

Related Projects

Official Telegram Libraries

• TDLib: Cross-platform library for building Telegram clients
• Telegram Database Library: Core library used by telegram-bot-api

Docker Alternatives

While this is an unofficial Docker wrapper, other community projects exist:

• Check Docker Hub for alternative implementations
• Consider official binaries for direct deployment
• Evaluate based on maintenance, security, and features

This project aims to provide a minimal, secure, and well-maintained Docker wrapper with clear documentation and multi-architecture support.

Staying Updated

Track Upstream Changes

1. Watch the repository: Star and watch tdlib/telegram-bot-api
2. Subscribe to @BotNews: Get official announcements
3. Review release notes: Check changes before upgrading

Update Your Deployment

Pull latest image:

docker pull ragnarok22/telegram-bot-api-docker:latest

Restart with new version:

docker compose down
docker compose pull
docker compose up -d

Verify version:

docker logs telegram-bot-api | grep "Starting telegram-bot-api"

Support and Community

Get help and connect with other users:

• Docker project: GitHub Discussions
• Bot development: @BotTalk on Telegram
• Official support: Telegram Bot API documentation

When asking for help, always specify whether your issue is Docker-related or concerns the upstream Telegram Bot API server functionality.