Multi-Architecture Support

Running on AMD64 and ARM64 platforms including Apple Silicon

The Telegram Bot API Docker image is built as a multi-architecture image, supporting both linux/amd64 and linux/arm64 platforms.

Supported Architectures

The official image supports the following platforms:

linux/amd64

Standard x86-64 architecture for most cloud servers and desktop systems

linux/arm64

64-bit ARM architecture for Apple Silicon, Raspberry Pi 4+, and ARM-based cloud instances

The multi-arch build is configured in the GitHub Actions workflow (docker-release.yml:41-51):

- name: Build and push (multi-arch)
  uses: docker/build-push-action@v6
  with:
    context: .
    file: ./Dockerfile
    push: ${{ github.event_name != 'pull_request' }}
    platforms: linux/amd64,linux/arm64
    tags: ${{ steps.metadata.outputs.tags }}
    labels: ${{ steps.metadata.outputs.labels }}
    cache-from: type=gha
    cache-to: type=gha,mode=max

Automatic Platform Selection

Docker automatically selects the correct image variant based on your system architecture:

docker pull ragnarok22/telegram-bot-api-docker

• On x86-64 systems (most cloud VMs, Intel/AMD desktops), Docker pulls the linux/amd64 variant
• On ARM64 systems (Apple Silicon Macs, ARM servers), Docker pulls the linux/arm64 variant

No manual configuration is needed in most cases.

Building Locally on Apple Silicon

You can build the image locally on Apple Silicon Macs:

cd ~/workspace/source
docker build -t telegram-bot-api:dev .

The Dockerfile uses --platform=$BUILDPLATFORM (Dockerfile:2) to optimize the build stage:

FROM --platform=$BUILDPLATFORM alpine:3.23.3 AS build-stage

This allows the build tools to run natively on your host architecture while producing the correct target binary.

Run the locally built image

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

Force Platform at Runtime

If you need to explicitly specify the platform (for example, to test ARM64 on an x86-64 system with emulation):

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

Or force the AMD64 variant:

docker run --rm --platform linux/amd64 \
  ragnarok22/telegram-bot-api-docker \
  ./telegram-bot-api --version

Running a non-native platform requires QEMU emulation, which is slower than native execution. Only use --platform for testing or compatibility checks.

Multi-Arch Build Pipeline

The release workflow uses Docker Buildx and QEMU to build both architectures (docker-release.yml:22-26):

- name: Set up QEMU (for multi-arch)
  uses: docker/setup-qemu-action@v3

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3

When a version tag like v9.5 or v9.5.0 is pushed, the workflow:

1. Runs smoke tests
2. Sets up QEMU for cross-platform emulation
3. Configures Docker Buildx for multi-arch builds
4. Builds and pushes both linux/amd64 and linux/arm64 images
5. Creates a manifest that Docker clients can use to pull the correct variant

The multi-arch manifest allows a single image tag (like ragnarok22/telegram-bot-api-docker:latest) to serve different architectures transparently.

Verification

Check which platform variant you’re running:

docker inspect ragnarok22/telegram-bot-api-docker | grep Architecture

For a running container:

docker inspect telegram-bot-api | grep Architecture