Бот фонда "Провидение"

Содержание

1. О чём проект?

2. Структура проекта

3. Подготовка к запуску

   3.1. Настройка poetry

   3.2. Настройка pre-commit

   3.3. Настройка переменных окружения

4. Запуск бота

   4.1. Запуск проекта локально

   4.2. Запуск в Docker

   4.3. GitHub Actions

1. О чём проект?

Проект телеграм-бота, который позволяет разгрузить кураторов/координаторов фонда “Провидение”, максимально автоматизировать процессы по взаимодействию с родителями и волонтерами.

...

2. Структура проекта

Имя	Описание
.data	Директория для хранения логов проекта.
bot	...
bot/conversations	...
core	...
src	...

3. Подготовка к запуску

Примечание: использование Poetry и pre-commit при работе над проектом обязательно.

3.1. Poetry (инструмент для работы с виртуальным окружением и сборки пакетов):

Poetry - это инструмент для управления зависимостями и виртуальными окружениями, также может использоваться для сборки пакетов. В этом проекте Poetry необходим для дальнейшей разработки приложения, его установка обязательна.

Как скачать и установить?

Установка:

Установите poetry следуя инструкции с официального сайта.

Команды для установки:

Для UNIX-систем и Bash on Windows вводим в консоль следующую команду:

curl -sSL https://install.python-poetry.org | python -

Для WINDOWS PowerShell:

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

После установки перезапустите оболочку и введите команду

poetry --version

Если установка прошла успешно, вы получите ответ в формате

Poetry (version 1.3.1)

Для дальнейшей работы введите команду:

poetry config virtualenvs.in-project true

Выполнение данной команды необходимо для создания виртуального окружения в папке проекта.

После предыдущей команды создадим виртуальное окружение нашего проекта с помощью команды:

poetry install

Результатом выполнения команды станет создание в корне проекта папки .venv. Зависимости для создания окружения берутся из файлов poetry.lock (приоритетнее) и pyproject.toml

Для добавления новой зависимости в окружение необходимо выполнить команду

poetry add <package_name>

Пример использования:

poetry add starlette

Также poetry позволяет разделять зависимости необходимые для разработки, от основных. Для добавления зависимости необходимой для разработки и тестирования необходимо добавить флаг --dev

poetry add <package_name> --dev

Пример использования:

poetry add pytest --dev

Порядок работы после настройки

Чтобы активировать виртуальное окружение, введите команду:

poetry shell

Существует возможность запуска скриптов и команд с помощью команды без активации окружения:

poetry run <script_name>.py

Примеры:

poetry run python script_name>.py

poetry run pytest

poetry run black

Порядок работы в оболочке не меняется. Пример команды для Win:

python src\run_bot.py

Доступен стандартный метод работы с активацией окружения в терминале с помощью команд:

Для WINDOWS:

source .venv/Scripts/activate

Для UNIX:

source .venv/bin/activate

3.2. Pre-commit (инструмент автоматического запуска различных проверок перед выполнением коммита):

Настройка pre-commit

pre-commit install

Далее при каждом коммите у вас будет происходить автоматическая проверка линтером, а так же будет происходить автоматическое приведение к единому стилю.

3.3. Настройка переменных окружения

Перед запуском проекта необходимо создать копию файла .env.example, назвав его .env и установить значение токена бота

4. Запуск бота

Возможен запуск бота в режимах polling или webhook.

4.1. Запуск проекта локально

Запуск проекта локально

4.1.1. Запуск в режиме Polling

python src/main.py

4.1.2. Запуск в режиме Webhook

Отладка приложения с ботом в режиме webhook на локальном компьютере требует выполнения дополнительных действий:

Необходимые действия

В случае отсутствия сервера с доменным именем и установленным SSL-сертификатом, для отладки приложения можно воспользоваться ngrok для построения туннеля до вашего компьютера.
Для этого необходимо:

• Скачать и установить ngrok
• Зарегистрироваться в сервисе ngrok и получить токен
• Зарегистрировать полученный токен на локальном комьютере

ngrok config add-authtoken <ваш токен>

• Запустить тоннель ngrok

ngrok http 8000 --host-header=site.local

• Скопировать из консоли адрес (https), предоставленный сервисом ngrok, в переменную окружения APPLICATION_URL:

APPLICATION_URL=https://1234-56-78-9.eu.ngrok.io # пример

• Запустить приложение с ботом в режиме webhook (см. выше)

python src/run_webhook_api.py

Более подробная информация об использовании сервиса ngrok доступна на официальном сайте

python src/run_webhook_api.py

4.2. Запуск проекта в Docker

Запуск проекта через Docker

Можно запустить бота через docker-compose в тестовом режиме. Для этого в корневой папке проекта выполнить команду

docker-compose up -d --build

4.3. GitHub Actions деплой на удаленный сервер

Warning

Не меняйте переменные POSTGRES_, если проект уже запущен на сервере.

Запуск проекта на сервере в docker-контейнере

Workflow:

• style_check - проверка кода на соответствие стандарту PEP8;
• providenie - автоматический билд и деплой проекта на боевой сервер;

Каждый push в release-ветку будет запускать воркфлоу providenie.

Стадии:

• Сборка docker-image bot и размещение в Packages репозитория.
• Деплой на сервер
• • Копирование docker-compose.yaml, nginx.conf и providenie.service (Unit для обслуживания контейнеров с помощью systemd)
• • Скачивание обновленного docker-образа и перезапуск контейнеров

Процесс построен с учетом как того, что сервер может быть пуст, так и того, что на нем уже запущен проект.

Подготовка сервера:

1. Войдите на свой удаленный сервер в облаке.
2. Установите docker:

sudo apt install docker.io

3. Установите docker-compose, с этим вам поможет официальная документация.
4. В репозитории на Гитхабе добавьте данные в Settings -> Secrets -> Actions -> New repository secret:

DOCKER_USERNAME - ваш username на dockerhub
DOCKER_PASSWORD - ваш пароль на dockerhub

USER - имя пользователя для подключения к серверу
HOST - IP-адрес вашего сервера
SSH_KEY - скопируйте приватный ключ с компьютера, имеющего доступ к боевому серверу (cat ~/.ssh/id_rsa)
PASSPHRASE - если при создании ssh-ключа вы использовали фразу-пароль, то сохраните её в эту переменную

TELEGRAM_TOKEN=5274023561:AAH3lUgvoGvLN51wtMze_ZGrTO0RRHGTuJM
[email protected]
EMAIL_BOT_PASSWORD=EmailPassword
[email protected]
LOG_LEVEL=INFO

# Переменные для подключения к БД
POSTGRES_USER=user
POSTGRES_PASSWORD=password
POSTGRES_DB=test_db
POSTGRES_SERVER=db
POSTGRES_PORT=5432

# Переменные JWT
TOKEN_SECRET_KEY=my_secret_key
TOKEN_ALGORITHM=HS256
TOKEN_EXPIRE_MINUTES=30

# Переменные для создания первого админа.
FIRST_SUPERUSER_TG_ID=tg_id
FIRST_SUPERUSER_FIRST_NAME=first_name
FIRST_SUPERUSER_USER_NAME=username
FIRST_SUPERUSER_PASSWORD=password
FIRST_SUPERUSER_IS_ADMIN=True