Health Checks

Monitor container health and integrate with orchestration tools

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