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.

This page covers building the Docker image from source, including the multi-stage build process, build arguments, and platform-specific builds.

​
Dockerfile Structure

The project uses a two-stage build to minimize the final image size:

​
Stage 1: Build Stage

Compiles the Telegram Bot API server from source: 
FROM --platform=$BUILDPLATFORM alpine:3.23.3 AS build-stage

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

# Shallow clone default branch with submodules
RUN git clone --depth 1 \
      --recurse-submodules --shallow-submodules \
      https://github.com/tdlib/telegram-bot-api.git /telegram-bot-api

WORKDIR /telegram-bot-api

RUN rm -rf build && \
    mkdir build && \
    cd build && \
    cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX:PATH=.. .. && \
    cmake --build . --target install
Key features:
  • Uses --platform=$BUILDPLATFORM for faster cross-compilation
  • Shallow clones the upstream repository to reduce build time
  • Compiles with Release configuration for optimal performance
  • Installs build dependencies only in this stage

​
Stage 2: Runtime Stage

Creates the minimal production image: 
FROM alpine:3.23.3

# Copy only the necessary files from the build stage
COPY --from=build-stage /telegram-bot-api/bin/ /telegram-bot-api/bin/

RUN apk add --no-cache libstdc++ libgcc && \
    addgroup -S botapi && adduser -S -G botapi botapi && \
    chown -R botapi:botapi /telegram-bot-api/bin && \
    mkdir -p /data/logs /tmp && \
    chown -R botapi:botapi /data /tmp

WORKDIR /telegram-bot-api/bin

COPY --chmod=755 entrypoint.sh /telegram-bot-api/bin/entrypoint.sh

VOLUME /data/logs

EXPOSE 8081 8082

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD wget -qO- http://localhost:8081/ || exit 1

USER botapi

ENTRYPOINT ["./entrypoint.sh"]
Key features:
  • Only runtime dependencies (libstdc++, libgcc) are installed
  • Runs as non-root user botapi for security
  • Includes health check for container orchestration
  • Exposes ports 8081 (API) and 8082 (stats)

​
Building Locally

1

Navigate to project directory

Ensure you’re in the directory containing the Dockerfile:
cd /path/to/telegram-bot-api-docker
2

Build the image

Build with a custom tag:
docker build -t telegram-bot-api:dev .
This creates an image tagged as telegram-bot-api:dev.
3

Verify the build

Check that the image was created:
docker images telegram-bot-api
Test the binary version:
docker run --rm telegram-bot-api:dev ./telegram-bot-api --version

​
Build Arguments and Customization

The Dockerfile supports Docker’s built-in build arguments for multi-platform builds:

​
Platform-Specific Builds

Build for a specific platform: 
# Build for ARM64
docker build --platform linux/arm64 -t telegram-bot-api:arm64 .

# Build for AMD64
docker build --platform linux/amd64 -t telegram-bot-api:amd64 .

​
Multi-Architecture Build

Create a multi-arch manifest (requires Docker Buildx): 
# Create and use a new builder
docker buildx create --use

# Build for multiple platforms
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t telegram-bot-api:multi \
  --load \
  .
The --platform=$BUILDPLATFORM instruction in the build stage ensures cross-compilation uses the host’s native architecture, significantly speeding up builds on Apple Silicon and other ARM64 hosts.

​
Image Layers and Optimization

The two-stage build provides several optimizations:
  1. Reduced image size: Build tools (cmake, gcc, git) are excluded from the final image
  2. Faster builds: Shallow git clone reduces download time
  3. Layer caching: Dependencies are installed before source compilation
  4. Security: Minimal runtime dependencies reduce attack surface
Typical image sizes:
  • Build stage: ~500-600 MB
  • Final image: ~50-60 MB

​
Building on Apple Silicon

On Apple Silicon (M1/M2/M3), Docker automatically builds for linux/arm64/v8: 
docker build -t telegram-bot-api:dev .
To build for AMD64 (x86_64) on Apple Silicon: 
docker build --platform linux/amd64 -t telegram-bot-api:amd64 .
Cross-platform builds (e.g., building AMD64 on ARM64) use QEMU emulation and are significantly slower than native builds.

​
Understanding the Build Process

The build follows these steps:
1

Build stage initialization

  • Pull Alpine 3.23.3 base image for the build platform
  • Install C++ toolchain, CMake, and dependencies
2

Source code retrieval

  • Shallow clone telegram-bot-api repository
  • Recursively clone submodules (TDLib dependencies)
3

Compilation

  • Configure CMake with Release build type
  • Compile telegram-bot-api binary
  • Install to /telegram-bot-api/bin
4

Runtime image creation

  • Start fresh Alpine 3.23.3 image
  • Copy only the compiled binary from build stage
  • Install minimal runtime libraries
5

Security hardening

  • Create non-root botapi user and group
  • Set file ownership and permissions
  • Configure volume mounts and exposed ports
6

Entrypoint setup

  • Copy entrypoint.sh script
  • Set as default command
  • Configure health check

​
Build Cache

Docker caches layers to speed up subsequent builds. To force a complete rebuild: 
docker build --no-cache -t telegram-bot-api:dev .
To use GitHub Actions cache (when available locally): 
docker buildx build \
  --cache-from type=gha \
  --cache-to type=gha,mode=max \
  -t telegram-bot-api:dev \
  .

​
Troubleshooting Build Issues

​
Build fails during git clone

Ensure you have internet connectivity and GitHub is accessible: 
curl -I https://github.com

​
Build fails during compilation

Check available disk space and memory: 
df -h
free -h
Increase Docker’s memory allocation in Docker Desktop settings if needed (recommend 4GB+).

​
Platform mismatch errors

Explicitly specify the target platform: 
docker build --platform linux/amd64 -t telegram-bot-api:dev .

Build docs developers (and LLMs) love

Get started for freeTalk to us