Skip to main content
Docker provides the easiest way to deploy the VBB Telegram Bot with all dependencies containerized and automatically configured.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Docker Engine (20.10 or higher)
  • Docker Compose (v2.0 or higher)
  • Git (to clone the repository)
You’ll need a Telegram Bot token from @BotFather before running the bot. Message BotFather with /newbot to create a new bot and receive your token.

​
Quick start

The simplest way to get started:
1

Configure the bot

Copy the example configuration file and add your bot token:
cp example.toml config.toml
Edit config.toml and add your bot token and owner ID. See the Configuration page for details.
2

Build and start

Build and start all services with a single command:
docker-compose up --build
This command will:
  • Build the bot Docker image from the Dockerfile
  • Pull the PostgreSQL image
  • Create a Docker network for the services
  • Start both the bot and database containers
  • Create a persistent volume for database data
The bot is now running and ready to receive messages on Telegram.

​
Docker Compose configuration

The docker-compose.yml file defines two services:

​
App service

services:
  app:
    build: .
    container_name: app
    depends_on:
      - db
    environment:
      - DATABASE_URL=postgresql+asyncpg://postgres:postgres@db:5432/vbb
      - TZ=Europe/Berlin
The app service:
  • Builds from the local Dockerfile
  • Waits for the database service to start
  • Connects to PostgreSQL using the DATABASE_URL environment variable
  • Sets timezone to Europe/Berlin (adjust for your location)

​
Database service

  db:
    image: postgres:latest
    container_name: postgres_db
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: vbb
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
The database service:
  • Uses the official PostgreSQL image
  • Creates a database named vbb automatically
  • Exposes port 5432 for external access (optional)
  • Persists data in a named volume

​
Dockerfile structure

The bot’s Dockerfile is minimal and efficient: 
FROM python:3.12
COPY . .
RUN pip install -r requirements.txt
CMD ["python", "-m", "app"]
This:
  1. Uses Python 3.12 as the base image
  2. Copies all application files into the container
  3. Installs Python dependencies
  4. Sets the default command to run the bot

​
Managing the deployment

​
Start in detached mode

Run the bot in the background: 
docker-compose up -d

​
View logs

Monitor the bot’s output: 
docker-compose logs -f app
View database logs: 
docker-compose logs -f db

​
Stop the services

Stop all running containers: 
docker-compose down
Stop and remove all data (including the database): 
docker-compose down -v
Using the -v flag will delete all stored addresses and user data. Only use this if you want to completely reset the bot.

​
Restart the bot

Restart just the bot service: 
docker-compose restart app

​
Rebuild after code changes

After making changes to the code, rebuild and restart: 
docker-compose up --build -d

​
Environment variables

The Docker Compose configuration uses environment variables to configure the bot:
VariableDescriptionDefault Value
DATABASE_URLPostgreSQL connection stringpostgresql+asyncpg://postgres:postgres@db:5432/vbb
TZContainer timezoneEurope/Berlin
You can override these in the docker-compose.yml file or create a .env file.

​
Production deployment

For production environments, consider these improvements:

​
Use secrets for sensitive data

Instead of hardcoding passwords in docker-compose.yml, use Docker secrets or environment files: 
services:
  db:
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password

secrets:
  db_password:
    file: ./secrets/db_password.txt

​
Add restart policies

Ensure the bot restarts automatically: 
services:
  app:
    restart: unless-stopped
  db:
    restart: unless-stopped

​
Configure resource limits

Limit memory and CPU usage: 
services:
  app:
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M

​
Set up database backups

Regularly backup the PostgreSQL data volume to prevent data loss.

​
Troubleshooting

​
Container fails to start

Check the logs for errors: 
docker-compose logs app
Common issues:
  • Missing or invalid config.toml file
  • Incorrect bot token
  • Database connection problems

​
Database connection errors

Ensure the database container is healthy: 
docker-compose ps
If the database is restarting, check its logs: 
docker-compose logs db

​
Port conflicts

If port 5432 is already in use, modify the port mapping in docker-compose.yml: 
ports:
  - "5433:5432"  # Use 5433 on host instead

​
Next steps

  • Learn about all configuration options in Configuration
  • Set up monitoring and logging for production
  • Configure automated backups for the database

Build docs developers (and LLMs) love

Get started for freeTalk to us