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.

​
Prerequisites

Before you begin, ensure you have:

​
Pull the Image

The image is published to Docker Hub as ragnarok22/telegram-bot-api-docker. It supports multiple architectures (linux/amd64 and linux/arm64), so Docker will automatically select the correct variant for your platform. 
docker pull ragnarok22/telegram-bot-api-docker
The image is multi-arch and works on both x86_64 and ARM64 platforms (including Apple Silicon Macs).

​
Basic Usage

​
Running with Environment File

The recommended approach is to use an .env file to manage your configuration:
1

Create the .env file

Create a .env file in your working directory with your API credentials:
.env
TELEGRAM_API_ID=12345
TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef
Get your credentials from my.telegram.org.
2

Start the container

Run the container with the environment file:
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
3

Verify the server is running

Test the API endpoint with your bot token:
curl http://localhost:8081/bot<YOUR_BOT_TOKEN>/getMe

​
Running with Inline Environment Variables

You can also pass environment variables directly via the -e flag: 
docker run -d --name telegram-bot-api \
  -e TELEGRAM_API_ID=12345 \
  -e TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef \
  -p 8081:8081 -p 8082:8082 \
  -v "$(pwd)/data:/data" \
  ragnarok22/telegram-bot-api-docker
Avoid exposing credentials in your shell history. Use an .env file or Docker secrets for production deployments.

​
Port Mappings

The server exposes two ports:
PortPurposeEnvironment Variable
8081HTTP API endpointTELEGRAM_HTTP_PORT
8082Statistics endpointTELEGRAM_HTTP_STAT_PORT

​
Default Port Configuration

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

​
Custom Port Configuration

To use different ports, set the environment variables and update your port mappings: 
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
When changing the internal ports via environment variables, ensure your -p port mappings match.

​
Volume Mounts

Persistent storage is essential for maintaining bot data, logs, and session information.

​
Data Directory

The default data directory inside the container is /data. Mount a host directory to preserve data across container restarts: 
docker run -d --env-file .env \
  -p 8081:8081 -p 8082:8082 \
  -v "$(pwd)/data:/data" \
  ragnarok22/telegram-bot-api-docker
The container will store:
  • Bot session data in /data
  • Logs in /data/logs/telegram-bot-api.log (by default)

​
Custom Data Directory

You can customize the data directory location: 
docker run -d --env-file .env \
  -e TELEGRAM_DIR=/custom-data \
  -p 8081:8081 -p 8082:8082 \
  -v "$(pwd)/custom-data:/custom-data" \
  ragnarok22/telegram-bot-api-docker

​
Logs Directory

By default, logs are written to /data/logs/telegram-bot-api.log. You can customize the log file path: 
docker run -d --env-file .env \
  -e TELEGRAM_LOG_FILE=/data/logs/bot.log \
  -p 8081:8081 -p 8082:8082 \
  -v "$(pwd)/data:/data" \
  ragnarok22/telegram-bot-api-docker

​
Advanced Examples

​
Running with Local Mode

Local mode (--local flag) allows the server to serve local files. Enable it with: 
docker run -d --env-file .env \
  -e TELEGRAM_LOCAL=true \
  -p 8081:8081 -p 8082:8082 \
  -v "$(pwd)/data:/data" \
  ragnarok22/telegram-bot-api-docker
Local mode should only be enabled in trusted environments with proper network isolation, as it allows serving local files.

​
Passing Additional Upstream Flags

Use TELEGRAM_EXTRA_ARGS to pass additional flags to the underlying 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 \
  -v "$(pwd)/data:/data" \
  ragnarok22/telegram-bot-api-docker

​
Running Without Data Persistence

For testing purposes, you can run without volume mounts (data will be lost on container restart): 
docker run -d --env-file .env \
  -p 8081:8081 -p 8082:8082 \
  ragnarok22/telegram-bot-api-docker

​
Custom Command Execution

Bypass the default entrypoint to run custom commands: 
docker run --rm ragnarok22/telegram-bot-api-docker ./telegram-bot-api --version

​
Container Management

​
View Container Logs

docker logs telegram-bot-api

​
View Live Logs

docker logs -f telegram-bot-api

​
Stop the Container

docker stop telegram-bot-api

​
Start the Container

docker start telegram-bot-api

​
Remove the Container

docker rm telegram-bot-api

​
Platform-Specific Notes

​
Apple Silicon and ARM64

The image automatically selects the correct architecture. To explicitly force a platform: 
docker run --rm --platform linux/arm64/v8 \
  ragnarok22/telegram-bot-api-docker ./telegram-bot-api --version

​
Building Locally

If you prefer to build from source: 
docker build -t telegram-bot-api:dev .
Then run your local build: 
docker run -d --env-file .env \
  -p 8081:8081 -p 8082:8082 \
  -v "$(pwd)/data:/data" \
  telegram-bot-api:dev

​
Troubleshooting

Missing Credentials

Ensure TELEGRAM_API_ID and TELEGRAM_API_HASH are set in your .env file or passed via -e flags.

Permission Issues

Create the ./data directory before first run and ensure it is writable:
mkdir -p ./data && chmod 755 ./data

Port Conflicts

If ports 8081 or 8082 are already in use, change the port mappings:
docker run -d --env-file .env -p 9081:8081 -p 9082:8082 ...

API Call Failures

Check container logs for errors:
docker logs telegram-bot-api
And inspect the log file inside the container:
docker exec telegram-bot-api cat /data/logs/telegram-bot-api.log

​
Next Steps

Docker Compose

Set up the server using Docker Compose for easier management

Configuration

Learn about all available configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us