Run multiple stateful Telegram bots on a single host

TL&DR.

tgbot-swarm sets up a container running nginx and nodejs controller that generates reverse proxy configs for nginx and reloads nginx when containers are started and stopped. It also creates self-signed certificate and exposes it through docker shared volume, making it easy to start multiple containers serving independent Telegram bots on a single host.

Quick start

git clone https://github.com/xyhtac/tgbot-swarm.git
cd tgbot-swarm
sudo mkdir -p \
  /opt/swarm-certificate \
  /opt/swarm-datastore \
  /opt/swarm-datastore-state
export BOT_TOKEN=telegram_bot_token
export SWARM_DB_PASS=database_password_for_bot_application
docker compose up -d

Abstract.

Telegram offers JSON-based, accessible via a RESTful control webhook API updates to push data to the handler application running as a publicly available https server on one of valid ports (80, 443, 88 or 8443) with self-signed or CA-signed certificate. Popular and well-maintained open source bot libraries widely used by developers (Telebot, Telegraf, etc.) may serve several bot tokens per process, but it comes with a cost of combining multiple bot logic into one source repo. Dockerization is the key.

Problem.

Running multiple instances of dockerized bot applications on a single host considering a limited number of allowed ports requires nginx reverse proxy to take care of connection dispatch. Configuration of nginx has to be carefully maintained in regard with actual port settings of docker containers; SSL-certificates need to be consistent along nginx and all deployed bot applications. Stateful bot applications also need ther databases configured on host's docker network. Therefore, the amount of manwork required to set-up and maintain single-host multi-bot dockerized stateful infrastructure is significantly higher than the development process of the bot itself.

Solution.

To minimise our efforts in bot hosting deployment tgbot-swarm solves three scopes of tasks:

1. Provide a dockerized controller that monitors other containers through the docker.sock and extracts their environment parameters, generate and keep updated relevant nginx configurations that connect hostname paths to running containers, generate self-signed certificates and expose them via shared docker volume.

2. Provide a dockerized controller that monitors other containers through the docker.sock and extracts their environment parameters, generate and keep updated relevant mariaDB databases with credentials and expose database via docker network.

3. Provide Jenkins groovy pipelines to automate build, configuration and deployment of containers; generate unique paths using UUID and automatically choose available port on the host from a given range.

Docker Container Usage

Make sure Docker (20.10+) is installed on your system: docker --version

Create required directories and volumes

# Certificates
sudo mkdir -p /opt/swarm-certificate
docker volume create \
  --driver local \
  --opt type=none \
  --opt device=/opt/swarm-certificate \
  --opt o=bind \
  tgbot-swarm-certificates

# Database storage
sudo mkdir -p /opt/swarm-datastore
docker volume create \
  --driver local \
  --opt type=none \
  --opt device=/opt/swarm-datastore \
  --opt o=bind \
  tgbot-swarm-datastore

# Datastore controller state
sudo mkdir -p /opt/swarm-datastore-state
docker volume create \
  --driver local \
  --opt type=none \
  --opt device=/opt/swarm-datastore-state \
  --opt o=bind \
  tgbot-swarm-datastore-state

Create Docker network

docker network inspect tgbot-swarm >/dev/null 2>&1 || \
docker network create --driver bridge tgbot-swarm

Run separate docker containers

# Spin up tgbot-swarm nginx + controller
docker run -d --name tgbot-swarm-controller \
    --restart unless-stopped \
    --network tgbot-swarm \
    -v /var/run/docker.sock:/tmp/docker.sock:ro \
    -v tgbot-swarm-certificates:/etc/nginx/certs \
    -e HOSTNAME=foo.bar.com \
    -p 443:443/tcp  \
xyhtac/tgbot-swarm:latest

# Spin up tgbot-swarm mariadb + controller
docker run -d --name tgbot-swarm-datastore \
    --restart unless-stopped \
    --network tgbot-swarm \
    -v /var/run/docker.sock:/tmp/docker.sock:ro \
    -v tgbot-swarm-datastore:/var/lib/mysql \
    -v tgbot-swarm-datastore-state:/app/state \
    -e DB_PORT=3306 \
xyhtac/tgbot-swarm-datastore:latest

# Spin up an example Telegram bot
docker run -d --name tgbot-swarm-samplebot \
    --restart unless-stopped \
    --network tgbot-swarm \
    -e BOT_TOKEN=[SECRET_BOT_TOKEN] \
    -e SWARM_DB_PASS=[SECRET_DB_PASSWORD] \
    -e SWARM_DB_HOST=tgbot-swarm-datastore \
    -e SWARM_DB_STORE=samplebot \
    -e SWARM_PATH=samplebot \
    -e SWARM_PORT=3300 \
    -v tgbot-swarm-certificates:/app/certs:ro \
    -p 3300:3300/tcp  \
xyhtac/tgbot-swarm-samplebot:latest

License

tgbot-swarm is licensed under the MIT license for all open source applications.

Bugs and feature requests

Please report bugs here on Github. Guidelines for bug reports:

1. Use the GitHub issue search — check if the issue has already been reported.
2. Check if the issue has been fixed — try to reproduce it using the latest master or development branch in the repository.
3. Isolate the problem — create a reduced test case and a live example.

A good bug report shouldn't leave others needing to chase you up for more information. Please try to be as detailed as possible in your report. Feature requests are welcome. Please look for existing ones and use GitHub's "reactions" feature to vote.