Бэкенд проекта "Ломая барьеры"

Оглавление

Описание
- Технологии
Установка и запуск
Использование
Дополнительная информация

Проект включает в себя телеграм-бота и сайт администратора, которые используются для сбора ежедневных результатов заданий, выполненных детьми дома. Задания направлены на развитие социально-бытовых навыков, таких как чистка зубов, стирка и мытье посуды. По итогам трехмесячной смены "Умею жить" дети получают заслуженные награды.

В настоящее время отправка фотографий в общий чат является основным способом отчетности, что приводит к некоторым неудобствам. Например, большой объем фотографий необходимо анализировать вручную, а также возможны случаи повторной отправки изображений.

Для упрощения этого процесса мы работаем над внедрением новых инструментов отчетности, которые помогут сделать процесс более автоматизированным и эффективным.

Технологии

Установка и Запуск

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

Зависимости

Warning: Необходимы для дальнейшей разработки приложения.

Poetry

Это инструмент управления зависимостями и виртуальным окружением, также используется для упаковки проектов на Python.

Подробнее: https://python-poetry.org/

Установить, следуя официальным инструкциям.

https://python-poetry.org/docs/#installation
Изменить конфигурацию Poetry (опционально).
```
poetry config virtualenvs.in-project true
```
Note: Позволяет создавать виртуальное окружение в папке проекта.

Установка

Клонировать репозиторий.

git clone https://github.com/Studio-Yandex-Practicum/lomaya_baryery_backend.git
cd lomaya_baryery_backend

Создать и активировать виртуальное окружение.
```
poetry install
poetry shell
```
Настроить pre-commit.
```
pre-commit install
```
Note: Перед каждым коммитом будет запущен линтер и форматтер, который автоматически отформатирует код согласно принятому в команде codestyle.
Переименовать .env.example в .env и задать переменные окружения.
```
BOT_TOKEN=<Токен аутентификации бота>
APPLICATION_URL=https://example.com  # Необязательно, пример
```
Warning: Если не указано значение для APPLICATION_URL, форма регистрации в боте работать не будет.

Warning: Необходимо доменное имя с установленным SSL-сертификатом. Иначе обратитесь к разделу "Использование Ngrok".

Запуск

Выполнить запуск контейнеров docker.
```
docker-compose -f docker-compose.local.yaml up -d
```
Note: Будет поднята Postgres база данных, а также прокси-сервер nginx.
Применить миграции базы данных.
```
alembic upgrade head
```
Запустить сервер приложения.
```
python run.py
```

Использование

После выполнения инструкций, описанных в разделе "Установка и Запуск", вы сможете получить доступ к админке, перейдя по адресу http://localhost.

Также по адресу http://localhost/api/docs доступна полная документация API.

Полезная информация

Данный раздел содержит информацию, которая может быть полезна для разработчиков. Настоятельно рекомендуем каждому прочитать его хотя бы один раз.

Режимы работы бота

Запуск без API приложения

Выполнить скрипт запуска.
```
python run_bot.py
```
Warning: Возможно только в режиме polling.

Polling

Задать значение переменной окружения (.env).
```
BOT_WEBHOOK_MODE=False
```

Webhook

Задать значение переменным окружения (.env).
```
BOT_WEBHOOK_MODE=True
APPLICATION_URL=https://example.com  # Пример
```
Warning: Необходимо доменное имя с установленным SSL-сертификатом. Иначе обратитесь к разделу "Использование Ngrok".

Работа с базой данных

Тестовые данные

Применить существующие миграции.
```
alembic upgrade head
```
Выполнить скрипт для наполнения базы тестовыми данными.
```
python -m data_factory.main
```
Warning: Использование в команде флага --delete перезапишет все данные. Подробнее: data_factory/README.md

Создание миграций

Применить существующие миграции.
```
alembic upgrade head
```
Создать новую миграцию.
```
alembic revision --autogenerate -m "<Название миграции>"
```
В название миграции указывается для какого поля или модели внесены изменения, например:
- add_shift_model
- shift_add_field_title
- shift_remove_field_title
Повторить пункт 1, для применения созданной миграции.

Откат миграций

Откатить последнюю миграцию.
```
alembic downgrade -1
```

Миграции с Enum-полем

Warning: При использовании ENUM-классов необходимо вручную определить создание и удаление типа в миграции.

Note: Далее приведены инструкции для поля "статус" с заранее разрешенными значениями.

Описать тип.

STATUS_ENUM_POSTGRES = postgresql.ENUM('started', 'finished', 'preparing', 'cancelled', name='shift_status', create_type=False)
STATUS_ENUM = sa.Enum('started', 'finished', 'preparing', 'cancelled', name='shift_status')
STATUS_ENUM.with_variant(STATUS_ENUM_POSTGRES, 'postgresql')

Добавить к полю.

sa.Column('status', STATUS_ENUM, nullable=False),

Прописать удаление при откате миграции.
```
STATUS_ENUM.drop(op.get_bind(), checkfirst=True)
```

Полный пример миграции

"""init

Revision ID: bc61d3dfbfa8
Revises:
Create Date: 2022-09-18 07:27:34.175636

"""
from alembic import op
import sqlalchemy as sa
from sqlalchemy.dialects import postgresql

# revision identifiers, used by Alembic.
revision = 'bc61d3dfbfa8'
down_revision = None
branch_labels = None
depends_on = None

STATUS_ENUM_POSTGRES = postgresql.ENUM('started', 'finished', 'preparing', 'cancelled', name='shift_status', create_type=False)
STATUS_ENUM = sa.Enum('started', 'finished', 'preparing', 'cancelled', name='shift_status')
STATUS_ENUM.with_variant(STATUS_ENUM_POSTGRES, 'postgresql')

def upgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    op.create_table('shift',
    sa.Column('id', postgresql.UUID(as_uuid=True), nullable=False),
    sa.Column('created_at', sa.TIMESTAMP(), server_default=sa.text('CURRENT_TIMESTAMP'), nullable=False),
    sa.Column('updated_at', sa.TIMESTAMP(), server_default=sa.text('CURRENT_TIMESTAMP'), nullable=False),
    sa.Column('status', STATUS_ENUM, nullable=False),
    sa.Column('started_at', sa.DATE(), server_default=sa.text('CURRENT_TIMESTAMP'), nullable=False),
    sa.Column('finished_at', sa.DATE(), nullable=False),
    sa.PrimaryKeyConstraint('id')
    )
    # ### end Alembic commands ###

def downgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    op.drop_table('shift')
    STATUS_ENUM.drop(op.get_bind(), checkfirst=True)
    # ### end Alembic commands ###

Если добавили значения в choice так же прописываем:

def upgrade():
    with op.get_context().autocommit_block():
        op.execute("ALTER TYPE status ADD VALUE 'REJECTED'")

Для отката миграции:

Переименовываем текущий тип;
Создаем новый (с прежними значениями);
Приписываем новый тип для таблицы;
Удаляем старый тип.

def downgrade():
    op.execute("ALTER TYPE status RENAME TO status_old")
    op.execute("CREATE TYPE status AS ENUM('STARTED', 'ACCEPTED')")
    op.execute((
        "ALTER TABLE transactions ALTER COLUMN status TYPE status USING "
        "status::text::status"
    ))
    op.execute("DROP TYPE status_old")

Работа с Poetry

В этом разделе представлены наиболее часто используемые команды.

Подробнее: https://python-poetry.org/docs/cli/

Активировать виртуальное окружение

poetry shell

Добавить зависимость

poetry add <package_name>

Note: Использование флага --dev (-D) позволяет установить зависимость, необходимую только для разработки. Это полезно для разделения develop и prod зависимостей.

Запустить скрипт без активации виртуального окружения

poetry run <script_name>.py

Использование Ngrok

Этот раздел будет полезен, если у вас нет доменного имени с установленным SSL-сертификатом.

Ngrok — это инструмент, который позволяет создавать временный общедоступный адрес (туннель) для вашего локального сервера, находящимся за NAT или брандмауэром.

Подробнее: https://ngrok.com/

Установить, следуя официальным инструкциям.

https://ngrok.com/download
Запустить туннель.
```
ngrok http 80
```
Задать значение переменной окружения (.env).
```
APPLICATION_URL=https://1234-56-78-9.eu.ngrok.io  # Пример
```

Переменные окружения (.env)

# Переменные приложения
BOT_TOKEN=  # Токен аутентификации бота
BOT_WEBHOOK_MODE=False  # Запустить бота в режиме webhook(True) | polling(False)
APPLICATION_URL=  # Домен, на котором развернуто приложение
HEALTHCHECK_API_URL=http://127.0.0.1:8080/docs  # Эндпоинт для проверки API
DEBUG=False  # Включение(True) | Выключение(False) режима отладки
SECRET_KEY=a84167ccb889a32e12e639db236a6b98877d73d54b42e54f511856e20ccaf2ab  # Cекретный ключ для генерации jwt-токенов
ROOT_PATH=/api/  # Для корректной работы без прокси ставится пустая строка, для работы с прокси "/api/"

# Переменные базы данных
POSTGRES_DB=lomaya_baryery_db_local  # Название базы данных
POSTGRES_USER=postgres  # Логин для подключения к базе данных
POSTGRES_PASSWORD=postgres  # Пароль для подключения к базе данных
DB_HOST=localhost  # Название сервиса (контейнера)
DB_PORT=6100  # Порт для подключения к базе данных

# Настройки почтового сервера
MAIL_SERVER=smtp.yandex.ru  # Адрес постового сервиса
MAIL_PORT=465  # Порт для подключения к почтовому сервису
MAIL_LOGIN=  # Логин для подключения к почтовому сервису
MAIL_PASSWORD=  # Пароль для подключения к почтовому сервису
MAIL_STARTTLS=False  # True или False, использовать ли STARTTLS
MAIL_SSL_TLS=True  # True или False, использовать ли SSL и TLS
USE_CREDENTIALS=True
VALIDATE_CERTS=True

Name		Name	Last commit message	Last commit date
Latest commit History 2,533 Commits
.github/workflows		.github/workflows
data_factory		data_factory
fail2ban		fail2ban
nginx		nginx
src		src
static/tasks		static/tasks
.env.example		.env.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
Dockerfile		Dockerfile
README.md		README.md
alembic.ini		alembic.ini
docker-compose.local.yaml		docker-compose.local.yaml
docker-compose.prod.yaml		docker-compose.prod.yaml
docker-compose.stage.yaml		docker-compose.stage.yaml
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml
run.py		run.py
run_bot.py		run_bot.py
setup.cfg		setup.cfg
tasks.json		tasks.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Бэкенд проекта "Ломая барьеры"

Технологии

Установка и Запуск

Зависимости

Poetry

Установка

Запуск

Использование

Полезная информация

Режимы работы бота

Запуск без API приложения

Polling

Webhook

Работа с базой данных

Тестовые данные

Создание миграций

Откат миграций

Миграции с Enum-полем

Работа с Poetry

Активировать виртуальное окружение

Добавить зависимость

Запустить скрипт без активации виртуального окружения

Использование Ngrok

Переменные окружения (.env)

About

Releases

Packages

Contributors 63

Languages

Studio-Yandex-Practicum/lomaya_baryery_backend

Folders and files

Latest commit

History

Repository files navigation

Бэкенд проекта "Ломая барьеры"

Технологии

Установка и Запуск

Зависимости

Poetry

Установка

Запуск

Использование

Полезная информация

Режимы работы бота

Запуск без API приложения

Polling

Webhook

Работа с базой данных

Тестовые данные

Создание миграций

Откат миграций

Миграции с Enum-полем

Работа с Poetry

Активировать виртуальное окружение

Добавить зависимость

Запустить скрипт без активации виртуального окружения

Использование Ngrok

Переменные окружения (.env)

About

Resources

Stars

Watchers

Forks

Releases

Packages 0

Contributors 63

Languages

Packages