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.

The Telegram Bot API Docker image includes a built-in health check that monitors the HTTP API endpoint.

​
Built-in Health Check

The health check is configured in the Dockerfile (Dockerfile:49-50): 
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD wget -qO- http://localhost:8081/ || exit 1

​
How It Works

  • Endpoint: Checks http://localhost:8081/ (the default API port)
  • Interval: Runs every 30 seconds
  • Timeout: Each check must complete within 5 seconds
  • Retries: Marks the container as unhealthy after 3 consecutive failures
  • Command: Uses wget -qO- to test the HTTP endpoint
The health check verifies that the Telegram Bot API server is responding to HTTP requests.

​
Monitoring Container Health

​
Check health status with docker ps

docker ps
The STATUS column shows the health: 
CONTAINER ID   IMAGE                                STATUS                    PORTS
abc123def456   ragnarok22/telegram-bot-api-docker   Up 2 minutes (healthy)   0.0.0.0:8081->8081/tcp
Possible health states:
  • starting - Initial state before the first health check
  • healthy - Health check is passing
  • unhealthy - Health check failed after the configured retries

​
View detailed health check logs

docker inspect --format='{{json .State.Health}}' telegram-bot-api | jq
This shows the last 5 health check results with timestamps and exit codes: 
{
  "Status": "healthy",
  "FailingStreak": 0,
  "Log": [
    {
      "Start": "2026-03-07T10:30:00.123Z",
      "End": "2026-03-07T10:30:00.456Z",
      "ExitCode": 0,
      "Output": ""
    }
  ]
}

​
Integration with Orchestration Tools

The built-in health check integrates seamlessly with container orchestration platforms.

​
Docker Compose

Docker Compose automatically uses the HEALTHCHECK directive from the Dockerfile. No additional configuration is needed: 
services:
  telegram-bot-api:
    image: ragnarok22/telegram-bot-api-docker
    env_file: .env
    ports:
      - "8081:8081"
      - "8082:8082"
    volumes:
      - ./data:/data
Check health status: 
docker compose ps

​
Docker Swarm

Docker Swarm uses health checks for service availability and rolling updates: 
version: "3.8"
services:
  telegram-bot-api:
    image: ragnarok22/telegram-bot-api-docker
    deploy:
      replicas: 2
      update_config:
        order: start-first
        failure_action: rollback
    environment:
      - TELEGRAM_API_ID=${TELEGRAM_API_ID}
      - TELEGRAM_API_HASH=${TELEGRAM_API_HASH}
    ports:
      - "8081:8081"
Swarm waits for the health check to pass before routing traffic to new replicas.

​
Kubernetes

Kubernetes doesn’t automatically use Docker’s HEALTHCHECK, so you need to define liveness and readiness probes: 
apiVersion: v1
kind: Pod
metadata:
  name: telegram-bot-api
spec:
  containers:
  - name: telegram-bot-api
    image: ragnarok22/telegram-bot-api-docker
    ports:
    - containerPort: 8081
    - containerPort: 8082
    env:
    - name: TELEGRAM_API_ID
      valueFrom:
        secretKeyRef:
          name: telegram-credentials
          key: api-id
    - name: TELEGRAM_API_HASH
      valueFrom:
        secretKeyRef:
          name: telegram-credentials
          key: api-hash
    livenessProbe:
      httpGet:
        path: /
        port: 8081
      initialDelaySeconds: 10
      periodSeconds: 30
      timeoutSeconds: 5
      failureThreshold: 3
    readinessProbe:
      httpGet:
        path: /
        port: 8081
      initialDelaySeconds: 5
      periodSeconds: 10

​
Custom Health Check Configuration

You can override the default health check in Docker Compose: 
services:
  telegram-bot-api:
    image: ragnarok22/telegram-bot-api-docker
    env_file: .env
    ports:
      - "8081:8081"
      - "8082:8082"
    volumes:
      - ./data:/data
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:8081/"]
      interval: 15s
      timeout: 3s
      retries: 5
      start_period: 10s

​
Custom Health Check with Different Port

If you’ve configured a custom HTTP port: 
services:
  telegram-bot-api:
    image: ragnarok22/telegram-bot-api-docker
    environment:
      - TELEGRAM_API_ID=${TELEGRAM_API_ID}
      - TELEGRAM_API_HASH=${TELEGRAM_API_HASH}
      - TELEGRAM_HTTP_PORT=9000
    ports:
      - "9000:9000"
      - "8082:8082"
    volumes:
      - ./data:/data
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:9000/"]
      interval: 30s
      timeout: 5s
      retries: 3
Ensure the health check port matches your TELEGRAM_HTTP_PORT configuration, otherwise the container will be marked as unhealthy.

​
Disable Health Check

To disable the health check entirely: 
services:
  telegram-bot-api:
    image: ragnarok22/telegram-bot-api-docker
    env_file: .env
    ports:
      - "8081:8081"
      - "8082:8082"
    volumes:
      - ./data:/data
    healthcheck:
      disable: true
Disabling health checks removes automatic health monitoring. This is not recommended for production deployments.

​
Troubleshooting Unhealthy Containers

If your container is marked as unhealthy:
  1. Check the logs: 
    docker logs telegram-bot-api
  2. Verify the API is listening: 
    docker exec telegram-bot-api wget -qO- http://localhost:8081/
  3. Check if the port configuration matches: 
    docker exec telegram-bot-api ps aux | grep telegram-bot-api
  4. Inspect recent health check results: 
    docker inspect --format='{{json .State.Health.Log}}' telegram-bot-api | jq
Common causes:
  • API server failed to start due to missing credentials
  • Port mismatch between health check and TELEGRAM_HTTP_PORT
  • Insufficient resources (CPU/memory)
  • Network connectivity issues

Build docs developers (and LLMs) love

Get started for freeTalk to us