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