Powerful aiogram template

Telegram Bot API template, with aiogram, sqlalcermy + alembic and docker

Navigation

• Getting started
  • Simple use template
  • Configure environment variables
    • Bot settings
    • Database
    • Redis
    • Webhook
• Docker
  • Start bot
  • Manage bot container
  • View bot logs
  • Restart bot
  • Stop bot
  • Database postgres
    • Manage postgres via psql
    • Alembic migrations
      • Create revision
      • Upgrade database
    • Backup and restore
      • Dump database
      • Restore database
  • I18n locales
    • Create locales
    • Update locales
• Bot structure
• Auto deploy
  • Configure secrets

---

Getting started

Simple use template

Click here to create repository from this template or:

$ git clone https://github.com/netbriler/aiogram-sqlalchemy-template <your project name>
$ cd <your project name>
$ pip install -r requirements.txt
# run pooling
$ python app.py
# or webhook
$ python webhook.py

Configure environment variables

Copy file .env.dist and rename it to .env

$ cp .env.dist .env

Than configure variables

$ vim .env
# or 
$ nano .env

Bot settings:

ADMINS - administrators ids divided by ,

# example
ADMINS=12345678,12345677,12345676
# or one admin
ADMINS=12345678

BOT_TOKEN - bot token from @BotFather

# example
BOT_TOKEN=123452345243:Asdfasdfasf

RATE_LIMIT - throttling rate limit (anti-spam)

# example
RATE_LIMIT=0.5 # seconds

Database

Sqlite by default but if you want to use postgres you can configurate it

# Dababase postgres
DATABASE_USER=<some username>
DATABASE_PASS=<some password>
DATABASE_HOST=localhost
DATABASE_PORT=5432

DATABASE_NAME=<some database name>

Redis

By default the bot can be run without radish, but if you want you can configurate it

# example
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_DB=5

Webhook

If you are using pooling leave them blank

# example
WEBHOOK_PORT=8080                                # run webhook on port
WEBHOOK_HOST=https://example.com         # webhook domain must be https
WEBHOOK_PATH=/path/to/webhook            # some custom path to webhook where telegram will send updates

Docker

Start bot

# grant execution rights
$ chmod +x ./bin/entrypoint.sh

$ docker-compose up -d --force-recreate
# or if you have make you can simply type 
$ make run
# or only make
$ make 

# database migration
$ docker-compose exec bot alembic upgrade head
# or if you have make you can simply type 
$ make db_update

if you are using webhook you should uncomment ports line in docker-compose.yml

Manage bot container

$ docker-compose exec bot /bin/bash
# or if you have make you can simply type 
$ make exec

View bot logs

$ docker-compose logs -f bot
# or if you have make you can simply type 
$ make logs

Restart bot

$ docker-compose restart bot
# or if you have make you can simply type 
$ make restart

Rebuild bot

$ docker-compose build --no-cache
# or if you have make you can simply type 
$ make build

Stop bot

$ docker-compose stop
# or if you have make you can simply type 
$ make stop

Database postgres

Manage postgres via psql

$ docker-compose exec postgres psql -U postgres postgres
# or if you have make you can simply type 
$ make psql

Alembic migrations

Create revision

$ docker-compose exec bot alembic revision --autogenerate -m "<some revision message>"
# or if you have make you can simply type 
$ make db_revision -m "<some revision message>"

Upgrade database

$ docker-compose exec bot alembic upgrade head
# or if you have make you can simply type 
$ make db_upgrade

you can get more information on alembic docs

Backup and restore

Dump database

$ mkdir -p data/backups/postgres && docker-compose exec -T postgres pg_dump -U postgres postgres --no-owner | gzip -9 > data/backups/postgres/backup-$(shell date +%Y-%m-%d_%H-%M-%S).sql.gz
# or if you have make you can simply type 
$ make pg_dump

Restore database

$ mkdir -p data/backups/postgres && bash ./bin/pg_restore.sh
# or if you have make you can simply type 
$ make pg_restore

I18n locales

Create locales

first you should extract all messages from bot

$ pybabel extract --input-dirs=. -o data/locales/bot.pot --project=bot
# or if you have make you can simply type 
$ make pybabel_extract

then init languages

$ pybabel init -i data/locales/bot.pot -d data/locales -D bot -l <language code>
# or if you have make you can simply type 
$ make pybabel_init <language code>

finaly translate messages in /data/locales/<language code>/LC_MESSAGES/bot.po and compile translations

$ pybabel compile -d data/locales -D bot --statistics
# or if you have make you can simply type 
$ make pybabel_compile

Update locales

to add new messages to already existing translations you should extract again and then write this command

$ pybabel update -i data/locales/bot.pot -d data/locales -D bot
# or if you have make you can simply type 
$ make pybabel_update

and finaly translate and compile again

Bot structure

├───bin                 # some bath scripts for docker
├───bot
│   ├───filters         # some aiogram filters
│   ├───handlers
│   │   ├───errors      # error handlers
│   │   └───users       # message handlers
│   ├───keyboards
│   │   ├───default     # aiogram markups
│   │   └───inline      # aiogram inline markups
│   ├───middlewares     # aiogram middlewares
│   └───states          # aiogram states
├───data
│   ├───backups         # database backups
│   │   └───postgres
│   ├───locales         # i18n locales
│   └───logs            # bot logs
├───models              # database models
├───services            # database services
└───utils               # some helpful things

Auto deploy

Automatically deploy bot to your server by ssh using github actions

Configure secrets

you should configure github actions secrets on https://github.com/<username>/<repo>/settings/secrets/actions

HOST - ssh server

PORT - ssh server port, by default 22

USERNAME - ssh username

KEY - private ssh key

PROJECT_PATH - path to your cloned repository