Docker Compose Setup

Deploy the Telegram Bot API server using Docker Compose

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

1. 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
   
2. 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
   
3. Start the service

   Build and run the container:

   docker compose up -d --build
   
4. 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 Configuration

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:

1. Check if the API is responding:

   curl http://localhost:8081/
   

2. Verify the port configuration matches:

   docker compose config | grep -A 5 healthcheck
   

3. 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"

Next Steps

Configuration

Explore all available environment variables and configuration options

Docker Setup

Learn about running with docker run commands