Docker Compose Setup - Telegram Bot API Docker

Overview

Docker Compose provides a declarative way to configure and run the Telegram Bot API server. The repository includes a production-ready compose.yml file with health checks, resource limits, and proper restart policies.

Prerequisites

Before you begin:

Install Docker and Docker Compose (Get Docker)
Obtain API credentials from my.telegram.org
Create a .env file with your configuration

Quick Start

Clone or download the repository

Get the compose.yml file from the repository:

git clone https://github.com/ragnarok22/telegram-bot-api-docker.git
cd telegram-bot-api-docker

Create your .env file

Copy the example and add your credentials:

cp .env.example .env

Edit .env with your values:

.env

TELEGRAM_API_ID=12345
TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef

Start the service

Build and run the container:

docker compose up -d --build

Verify the deployment

Check the service status:

docker compose ps

Test the API:

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

Repository compose.yml

The repository includes a complete compose.yml file that builds from source:

compose.yml

services:
  telegram-api:
    build:
      context: .
      dockerfile: Dockerfile
    restart: unless-stopped
    ports:
      - "8081:8081"
      - "8082:8082"
    env_file: .env
    volumes:
      - ./data:/data
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:8081/"]
      interval: 30s
      timeout: 5s
      retries: 3
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "1.0"

Service Configuration Breakdown

build:
  context: .
  dockerfile: Dockerfile

Using the Published Image

If you prefer to use the pre-built image from Docker Hub instead of building from source, create a minimal compose.yml:

compose.yml

services:
  telegram-bot-api:
    image: ragnarok22/telegram-bot-api-docker
    restart: unless-stopped
    env_file: .env
    ports:
      - "8081:8081"
      - "8082:8082"
    volumes:
      - ./data:/data
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:8081/"]
      interval: 30s
      timeout: 5s
      retries: 3

This pulls the latest image from Docker Hub instead of building locally.

Using the published image is faster for deployment, while building from source gives you more control and allows you to modify the Dockerfile.

Health Checks

The health check configuration monitors the API endpoint to ensure the service is responsive:

healthcheck:
  test: ["CMD", "wget", "-qO-", "http://localhost:8081/"]
  interval: 30s
  timeout: 5s
  retries: 3

Health Check Behavior

Test: Makes an HTTP request to the API endpoint
Interval: Checks every 30 seconds
Timeout: Waits up to 5 seconds for a response
Retries: Marks the container as unhealthy after 3 consecutive failures

Viewing Health Status

docker compose ps

The STATUS column shows the health state:

healthy: Service is responding correctly
unhealthy: Service failed health checks
starting: Initial grace period before checks begin

Custom Health Check Port

If you change the HTTP port, update the health check accordingly:

services:
  telegram-bot-api:
    environment:
      - TELEGRAM_HTTP_PORT=9000
    ports:
      - "9000:9000"
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:9000/"]
      interval: 30s
      timeout: 5s
      retries: 3

Resource Limits

The deploy.resources.limits section prevents the container from consuming excessive system resources:

deploy:
  resources:
    limits:
      memory: 512M
      cpus: "1.0"

Memory Limit

The 512M memory limit is suitable for most bot API deployments. Increase it if you:

Serve many concurrent bots
Handle large file uploads/downloads
Experience out-of-memory errors

deploy:
  resources:
    limits:
      memory: 1G  # Increase to 1 GB

CPU Limit

The 1.0 CPU limit allows the container to use one full CPU core. Adjust based on your workload:

deploy:
  resources:
    limits:
      cpus: "2.0"  # Allow 2 CPU cores

Resource limits help prevent a single service from degrading system performance. Monitor your actual usage with docker stats to fine-tune these values.

Configuration with Environment Variables

Override configuration values by adding them to your .env file:

.env

TELEGRAM_API_ID=12345
TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef
TELEGRAM_HTTP_PORT=9000
TELEGRAM_HTTP_STAT_PORT=9001
TELEGRAM_LOCAL=true
TELEGRAM_EXTRA_ARGS=--max-webhook-connections 80

Or inline in the compose file:

compose.yml

services:
  telegram-bot-api:
    image: ragnarok22/telegram-bot-api-docker
    environment:
      - TELEGRAM_API_ID=12345
      - TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef
      - TELEGRAM_HTTP_PORT=9000

Avoid hardcoding credentials in compose.yml. Always use an .env file or Docker secrets for sensitive values.

Building from Source vs Using Published Image

Building from Source

Advantages:

Full control over the build process
Ability to modify the Dockerfile
Can use a specific upstream commit or branch
Useful for development and testing

Use when:

You need to customize the build
You want to track a specific upstream version
You’re contributing to the project

docker compose up -d --build

Using Published Image

Advantages:

Faster deployment (no build time)
Consistent, tested releases
Automatic platform detection (amd64/arm64)
Smaller storage footprint

Use when:

You want quick deployment
You trust the published releases
You don’t need custom modifications

docker compose pull
docker compose up -d

The published image is multi-arch and automatically selects the correct variant for your platform (x86_64 or ARM64).

Common Operations

Start Services

docker compose up -d

Stop Services

docker compose down

View Logs

# All logs
docker compose logs

# Follow logs in real-time
docker compose logs -f

# Logs for specific service
docker compose logs telegram-api

Restart Service

docker compose restart

Rebuild and Restart

docker compose up -d --build

View Service Status

docker compose ps

Execute Commands Inside Container

# View log file
docker compose exec telegram-api cat /data/logs/telegram-bot-api.log

# Get shell access
docker compose exec telegram-api sh

Remove All Data

This will delete all bot data and logs permanently.

docker compose down -v
rm -rf ./data

Advanced Configuration

Multiple Service Stacks

Run multiple API instances on different ports:

compose.yml

services:
  telegram-api-prod:
    image: ragnarok22/telegram-bot-api-docker
    env_file: .env.prod
    ports:
      - "8081:8081"
      - "8082:8082"
    volumes:
      - ./data-prod:/data

  telegram-api-staging:
    image: ragnarok22/telegram-bot-api-docker
    env_file: .env.staging
    environment:
      - TELEGRAM_HTTP_PORT=9081
      - TELEGRAM_HTTP_STAT_PORT=9082
    ports:
      - "9081:9081"
      - "9082:9082"
    volumes:
      - ./data-staging:/data

Named Volumes

Use Docker-managed volumes instead of bind mounts:

compose.yml

services:
  telegram-bot-api:
    image: ragnarok22/telegram-bot-api-docker
    volumes:
      - telegram-data:/data

volumes:
  telegram-data:
    driver: local

Network Configuration

Isolate the service in a custom network:

compose.yml

services:
  telegram-bot-api:
    image: ragnarok22/telegram-bot-api-docker
    networks:
      - telegram-network

networks:
  telegram-network:
    driver: bridge

Troubleshooting

Service Won’t Start

Check the logs for errors:

docker compose logs telegram-api

Common issues:

Missing TELEGRAM_API_ID or TELEGRAM_API_HASH in .env
Port conflicts with existing services
Permission issues with the ./data directory

Health Check Failures

If the service is marked as unhealthy:

Check if the API is responding:
```
curl http://localhost:8081/
```

Verify the port configuration matches:

docker compose config | grep -A 5 healthcheck

Increase timeout or retries if needed

Build Failures

If building from source fails:

# Clean and rebuild
docker compose down
docker compose build --no-cache
docker compose up -d

Resource Exhaustion

Monitor container resource usage:

docker stats

Increase limits if needed:

deploy:
  resources:
    limits:
      memory: 1G
      cpus: "2.0"

Overview

Setup & Deployment

Configuration

Operations

Migration

Development

Reference

Documentation Index

​Overview

​Prerequisites

​Quick Start

​Repository compose.yml

​Service Configuration Breakdown

​Using the Published Image

​Health Checks

​Health Check Behavior

​Viewing Health Status

​Custom Health Check Port

​Resource Limits

​Memory Limit

​CPU Limit

​Configuration with Environment Variables

​Building from Source vs Using Published Image

​Building from Source

​Using Published Image

​Common Operations

​Start Services

​Stop Services

​View Logs

​Restart Service

​Rebuild and Restart

​View Service Status

​Execute Commands Inside Container

​Remove All Data

​Advanced Configuration

​Multiple Service Stacks

​Named Volumes

​Network Configuration

​Troubleshooting

​Service Won’t Start

​Health Check Failures

​Build Failures

​Resource Exhaustion

​Next Steps

Configuration

Docker Setup

Build docs developers (and LLMs) love

Overview

Prerequisites

Quick Start

Repository compose.yml

Service Configuration Breakdown

Using the Published Image

Health Checks

Health Check Behavior

Viewing Health Status

Custom Health Check Port

Resource Limits

Memory Limit

CPU Limit

Configuration with Environment Variables

Building from Source vs Using Published Image

Building from Source

Using Published Image

Common Operations

Start Services

Stop Services

View Logs

Restart Service

Rebuild and Restart

View Service Status

Execute Commands Inside Container

Remove All Data

Advanced Configuration

Multiple Service Stacks

Named Volumes

Network Configuration

Troubleshooting

Service Won’t Start

Health Check Failures

Build Failures

Resource Exhaustion

Next Steps