Simple, but extensible template for telegram bot, using pyTelegramBotAPI and adaptix

git clone https://github.com/Cub11k/tgBotTemplate.git  # via HTTPS
# or
git clone [email protected]:Cub11k/tgBotTemplate.git  # via SSH

cd tgBotTemplate

• Change package name, description, version, author, homepage, etc. in pyproject.toml
• Create virtual environment or use the existing one
• Activate virtual environment
• Installation options
  • Install the package in editable mode
  • Install the dependencies from a lock-file without installing the package itself

# Option #1 - installing the package in editable mode
pip install -e .

# Option #2 - installing only the dependencies
pip install -r requirements.txt

In this template, the requirements.txt file is in fact a lock-file, generated using pip-compile

It contains a fixed set dependencies with strictly fixed versions (==) and is crucial for having stable reproducible builds in production. Not to be edited manually as it can lead to conflicts ❗ ❗

If you want to change this file, e.g. your set of dependencies in pyproject.toml has changed, or you want to update the versions of existing packages, simply run

# this will ensure that requirements.txt satisfies the constraints set in your project
# it will not change the versions of packages if they already satisfy the constraints set
pip-compile pyproject.toml -o requirements.txt

# to force the update use --upgrade or --upgrade-package for specific packages (can be used multiple times)
pip-compile pyproject.toml --upgrade -o requirements.txt
# or
pip-compile pyproject.toml --upgrade-package pytelegrambotapi --upgrade-package adaptix==3.0.0b7 -o requirements.txt

Before running the bot you'll have to configure the environment using the environment variables

The simplest way to run the bot using long polling is to use the launch-polling script

launch-polling <path-to-the-config-file>

To get more details about the script, run it with the --help flag

launch-polling --help

To run the bot using webhook, you'll have to adjust the module mybot:webhook according to the web-framework used

After that, you can launch the app using the web-server of your choice, e.g. gunicorn

gunicorn 'mybot:webhook_app()' --bind=$HOST:$PORT --workers-class=$WORKERS_CLASS

pip uninstall <your-package-name>

Beware that mybot is not the package name, but the name of the module, the package name is defined in pyproject.toml

In project root execute:

docker build -t tgbot .

In any case subsititute token with your Telegram Bot API Token

Run in interactive mode (TTY + stdin):

docker run -it --rm -e MYAPP_BOT_TOKEN=token tgbot

Run detached (in background) with restart policy:

docker run -d --restart unless-stopped -e MYAPP_BOT_TOKEN=token tgbot

Run detached with bind mounts:

docker run -d --restart unless-stopped -v ./config:/config -v ./logs:/logs -e MYAPP_BOT_TOKEN=token tgbot

By default provided docker-compose.yml will build project in new image and run it with redis instance as a state storage.

Provide .env file with MYAPP_BOT_TOKEN set to your Telegram Bot API Token.

Also in .env you can pass any configuration in env vars form according to your config.toml and config_env_mapping.toml.

docker compose up -d --build

docker compose down

By default there are 4 volumes created by docker-compose.yml:

1. config - directory with config.toml and config_env_mapping.toml which are used by running instance
2. logs - directory with logs (by default loggers are write in stdout and in files in this directory)
3. redis-config - redis configuration
4. redis-data - redis data storage (for persistence)

Feel free to contribute to the project by creating issues and pull requests