Running the Container

Learn how to run and manage the Telegram Bot API Docker container

This guide covers common operations for running and managing the Telegram Bot API container.

Running with Default Configuration

The simplest way to start the container with default settings:

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

This uses:

• Port 8081 for the HTTP API
• Port 8082 for statistics
• /data directory for bot data and logs
• Default log file at /data/logs/telegram-bot-api.log

Ensure your .env file contains TELEGRAM_API_ID and TELEGRAM_API_HASH before starting.

Running with Custom Ports

To use different ports, set the environment variables and map the corresponding host ports:

docker run -d --env-file .env \
  -e TELEGRAM_HTTP_PORT=9000 \
  -e TELEGRAM_HTTP_STAT_PORT=9001 \
  -p 9000:9000 -p 9001:9001 \
  ragnarok22/telegram-bot-api-docker

Make sure the -p port mappings match your TELEGRAM_HTTP_PORT and TELEGRAM_HTTP_STAT_PORT values.

Running with Local Mode Enabled

Enable local mode to allow the Bot API server to serve local files:

docker run -d --env-file .env \
  -e TELEGRAM_LOCAL=true \
  -p 8081:8081 -p 8082:8082 \
  ragnarok22/telegram-bot-api-docker

You can also use TELEGRAM_LOCAL=1 instead of true.

TELEGRAM_LOCAL should only be enabled in trusted environments with proper network isolation, as it allows serving local files.

Passing Extra Arguments

Use TELEGRAM_EXTRA_ARGS to pass additional flags directly to the upstream telegram-bot-api binary:

docker run -d --env-file .env \
  -e TELEGRAM_EXTRA_ARGS="--max-webhook-connections 50 --log-verbosity-level 3" \
  -p 8081:8081 -p 8082:8082 \
  ragnarok22/telegram-bot-api-docker

The entrypoint script (entrypoint.sh:62-64) appends these arguments to the final command:

if [ -n "${TELEGRAM_EXTRA_ARGS:-}" ]; then
  ARGS="$ARGS ${TELEGRAM_EXTRA_ARGS}"
fi

Viewing Logs

The default log file is located at /data/logs/telegram-bot-api.log inside the container.

View logs with docker logs

docker logs telegram-bot-api

View logs with docker logs (follow mode)

docker logs -f telegram-bot-api

View the log file directly

docker exec telegram-bot-api cat /data/logs/telegram-bot-api.log

Or, if you’ve mounted the volume, access it on the host:

cat ./data/logs/telegram-bot-api.log

Stopping and Restarting

Stop the container

docker stop telegram-bot-api

Start a stopped container

docker start telegram-bot-api

Restart the container

docker restart telegram-bot-api

Remove the container

docker rm telegram-bot-api

Stopping the container gracefully shuts down the Telegram Bot API server. Your bot data in /data persists if you’ve mounted a volume.

Using Custom Commands

You can bypass the default entrypoint logic by passing custom commands. The entrypoint script (entrypoint.sh:4-7) checks for positional arguments:

if [ "$#" -gt 0 ]; then
  exec "$@"
fi

Check the server version

docker run --rm ragnarok22/telegram-bot-api-docker ./telegram-bot-api --version

Run a shell inside the container

docker run --rm -it ragnarok22/telegram-bot-api-docker /bin/sh

Execute a custom script

docker run --rm -v "$(pwd)/scripts:/scripts" ragnarok22/telegram-bot-api-docker /scripts/my-script.sh

Custom commands are useful for debugging, inspecting the binary, or running one-off tasks without starting the full API server.