Volumes

The Telegram Bot API server requires persistent storage for bot data, logs, and temporary files. Understanding how volumes work is essential for data persistence, backups, and troubleshooting.

Volume Overview

The Docker image defines one named volume (source at Dockerfile:45) and uses several important directories:

/data - Primary working directory for bot data
/data/logs - Log file directory
/tmp - Temporary files for HTTP operations

Primary Volumes

/data - Bot Data Directory

The main working directory where the server stores all bot-related data. Default value: /data (configurable via TELEGRAM_DIR) Contains:

Bot session data (subdirectories named by bot user ID)
Database files
Downloaded media and files
Configuration state

Mount example:

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

Docker Compose:

services:
  telegram-bot-api:
    image: ragnarok22/telegram-bot-api-docker
    env_file: .env
    ports:
      - "8081:8081"
      - "8082:8082"
    volumes:
      - ./data:/data

Each bot’s data is stored in a subdirectory within /data named by its user ID. When migrating between servers, you can copy these subdirectories to preserve bot state.

/data/logs - Log Files

Directory for server log files. Default log file: /data/logs/telegram-bot-api.log (configurable via TELEGRAM_LOG_FILE) Mount example:

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

Since /data/logs is a subdirectory of /data, mounting /data automatically includes logs. Accessing logs:

# View logs on host
tail -f ./data/logs/telegram-bot-api.log

# View logs using docker logs
docker logs telegram-bot-api

# View logs inside container
docker exec telegram-bot-api cat /data/logs/telegram-bot-api.log

/tmp - Temporary Directory

Directory for HTTP server temporary files. Default value: /tmp (configurable via TELEGRAM_TEMP_DIR) Usage: Temporary storage for file uploads/downloads during HTTP operations. Mount example (if needed):

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

In most cases, you don’t need to mount /tmp as a volume. The container’s temporary filesystem is sufficient for transient data.

Volume Setup

Creating the Data Directory

Before first run, create the data directory and ensure proper permissions:

mkdir -p ./data/logs
chmod -R 755 ./data

The container runs as the botapi user (source at Dockerfile:35-38), which needs write access to these directories.

Permission Issues

If you encounter permission errors:

# Option 1: Make directory world-writable (simple but less secure)
chmod -R 777 ./data

# Option 2: Match the container user UID/GID
# The botapi user typically has UID/GID 100
sudo chown -R 100:100 ./data

Data Persistence

Why Volumes Matter

Without a mounted volume, data is stored inside the container’s ephemeral filesystem:

Data is lost when the container is removed
No easy way to backup or migrate data
Cannot access logs from the host

Bad example (no persistence):

# Data will be lost when container is removed!
docker run -d --env-file .env -p 8081:8081 ragnarok22/telegram-bot-api-docker

Good example (persistent data):

# Data persists on host filesystem
docker run -d --env-file .env -p 8081:8081 -v "$(pwd)/data:/data" ragnarok22/telegram-bot-api-docker

Container Lifecycle

With properly mounted volumes, you can safely:

Stop and start the container
Remove and recreate the container
Upgrade to a new image version
Move the data directory to another host

All bot data and session state will be preserved.

Backup and Migration

Backing Up Bot Data

Simple backup using tar:

# Stop the container first for consistency
docker stop telegram-bot-api

# Create backup
tar -czf telegram-bot-api-backup-$(date +%Y%m%d).tar.gz ./data

# Restart container
docker start telegram-bot-api

Restoring from Backup

# Stop container
docker stop telegram-bot-api

# Extract backup
tar -xzf telegram-bot-api-backup-20260307.tar.gz

# Ensure permissions
chmod -R 755 ./data

# Restart container
docker start telegram-bot-api

Migrating Between Servers

To move a bot to a new server:

On the old server:

# Stop container
docker stop telegram-bot-api

# Create archive
tar -czf telegram-bot-api-data.tar.gz ./data

# Transfer to new server
scp telegram-bot-api-data.tar.gz user@newserver:/path/to/destination/

On the new server:

# Extract data
tar -xzf telegram-bot-api-data.tar.gz

# Set permissions
chmod -R 755 ./data

# Start container with same configuration
docker run -d \
  --env-file .env \
  -p 8081:8081 \
  -v "$(pwd)/data:/data" \
  ragnarok22/telegram-bot-api-docker

Optional - logout from old server first: Before migrating, call the logOut method on the old server to ensure proper update delivery.

If the same bot is logged in on multiple servers simultaneously, update delivery is not guaranteed. Always logout from the old server before starting on the new one.

Custom Volume Configuration

Using Named Docker Volumes

Instead of bind mounts, you can use Docker named volumes:

# Create named volume
docker volume create telegram-bot-api-data

# Run with named volume
docker run -d \
  --env-file .env \
  -p 8081:8081 \
  -v telegram-bot-api-data:/data \
  ragnarok22/telegram-bot-api-docker

Docker Compose with named volume:

services:
  telegram-bot-api:
    image: ragnarok22/telegram-bot-api-docker
    env_file: .env
    ports:
      - "8081:8081"
      - "8082:8082"
    volumes:
      - telegram-data:/data

volumes:
  telegram-data:

Custom Directory Paths

Change the internal paths using environment variables:

docker run -d \
  --env-file .env \
  -e TELEGRAM_DIR=/custom/data \
  -e TELEGRAM_LOG_FILE=/custom/logs/api.log \
  -e TELEGRAM_TEMP_DIR=/custom/tmp \
  -p 8081:8081 \
  -v "$(pwd)/custom:/custom" \
  ragnarok22/telegram-bot-api-docker

When using custom paths, ensure the directories exist and are writable by the botapi user inside the container.

Monitoring Storage Usage

Check Volume Size

# Disk usage of data directory
du -sh ./data

# Detailed breakdown
du -h ./data | sort -hr | head -20

Check Docker Volume Usage

# List volumes and sizes
docker system df -v

# Inspect specific volume
docker volume inspect telegram-bot-api-data

Troubleshooting

Logs Not Appearing

If logs aren’t being written:

Check directory permissions:
```
ls -la ./data/logs
```

Verify the log path inside container:

docker exec telegram-bot-api ls -la /data/logs

Check for permission errors in container logs:
```
docker logs telegram-bot-api
```

Data Not Persisting

If data is lost after container restart:

Verify volume mount:

docker inspect telegram-bot-api | grep -A 10 Mounts

Ensure you’re not removing the volume:

# Wrong - removes volumes
docker rm -v telegram-bot-api

# Correct - keeps volumes
docker rm telegram-bot-api

Permission Denied Errors

If the container can’t write to /data:

# Check current permissions
ls -la ./data

# Fix permissions (run as root on host)
sudo chown -R 100:100 ./data
chmod -R 755 ./data

# Or make it world-writable (less secure)
chmod -R 777 ./data

Best Practices

Always mount /data - Never run without a persistent volume in production
Regular backups - Automate backups of your data directory
Monitor disk usage - Bot data can grow significantly over time
Use named volumes - For better Docker integration and portability
Test restores - Periodically verify your backups can be restored successfully
Separate logs - Consider mounting /data/logs separately for log rotation and management
Document your setup - Keep notes on your volume configuration and backup procedures

Overview

Setup & Deployment

Configuration

Operations

Migration

Development

Reference

Volume Overview

Primary Volumes

/data - Bot Data Directory

/data/logs - Log Files

/tmp - Temporary Directory

Volume Setup

Creating the Data Directory

Permission Issues

Data Persistence

Why Volumes Matter

Container Lifecycle

Backup and Migration

Backing Up Bot Data

Restoring from Backup

Migrating Between Servers

Custom Volume Configuration

Using Named Docker Volumes

Custom Directory Paths

Monitoring Storage Usage

Check Volume Size

Check Docker Volume Usage

Troubleshooting

Logs Not Appearing

Data Not Persisting

Permission Denied Errors

Best Practices

Build docs developers (and LLMs) love

Overview

Setup & Deployment

Configuration

Operations

Migration

Development

Reference

Documentation Index

​Volume Overview

​Primary Volumes

​/data - Bot Data Directory

​/data/logs - Log Files

​/tmp - Temporary Directory

​Volume Setup

​Creating the Data Directory

​Permission Issues

​Data Persistence

​Why Volumes Matter

​Container Lifecycle

​Backup and Migration

​Backing Up Bot Data

​Restoring from Backup

​Migrating Between Servers

​Custom Volume Configuration

​Using Named Docker Volumes

​Custom Directory Paths

​Monitoring Storage Usage

​Check Volume Size

​Check Docker Volume Usage

​Troubleshooting

​Logs Not Appearing

​Data Not Persisting

​Permission Denied Errors

​Best Practices

Build docs developers (and LLMs) love

Volume Overview

Primary Volumes

/data - Bot Data Directory

/data/logs - Log Files

/tmp - Temporary Directory

Volume Setup

Creating the Data Directory

Permission Issues

Data Persistence

Why Volumes Matter

Container Lifecycle

Backup and Migration

Backing Up Bot Data

Restoring from Backup

Migrating Between Servers

Custom Volume Configuration

Using Named Docker Volumes

Custom Directory Paths

Monitoring Storage Usage

Check Volume Size

Check Docker Volume Usage

Troubleshooting

Logs Not Appearing

Data Not Persisting

Permission Denied Errors

Best Practices