Skip to content

Studio-Yandex-Practicum/Tabit

BranchesTags

Repository files navigation

Tabit

Оглавление

  1. 📌 О проекте
  2. 🚀 Начало работы
  3. 💾 Работа с базой данных
  4. 👨‍💻 Разработка
  5. 🔄 CI/CD и деплой
  6. ▶️ Запуск приложения
  7. 📋 Справочник команд Makefile
  8. 🧪 Тестирование
  9. ❓ Часто встречающиеся ошибки

📌 О проекте

Tabit — онлайн-сервис для HR-специалистов и собственников компаний, который помогает:

  • 📊 Измерять эмоциональный климат в компании
  • 🔍 Выявлять выгорающих сотрудников
  • 💡 Обнаруживать внутренние проблемы компании
  • 📈 Отслеживать ключевые показатели (текучесть кадров, уровень конфликтности и доверия)

Требования к окружению: Python 3.12 или выше.

🚀 Начало работы

📦 Poetry

Poetry — это инструмент для управления зависимостями и виртуальными окружениями Python. В проекте Poetry является обязательным для разработки.

🔽 Установка Poetry

Установка Poetry

Следуйте официальной инструкции или используйте один из способов:

Через pip:

pip install poetry==1.7.1  # Последняя стабильная версия 1.x

Для UNIX-систем и WSL:

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

Для Windows PowerShell:

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

⚠️ Примечание: Рекомендуется использовать версию 1.x, так как версия 2.x может иметь отличия в командах и работе.

Проверка установки

poetry --version

⚠️ Примечание: Если poetry не найден, добавьте путь установки в переменную PATH вашей системы.

Настройка Poetry для проекта

  1. Настройте создание виртуального окружения в папке проекта:

    poetry config virtualenvs.in-project true

  2. Установите зависимости проекта:

    poetry install
🔽 Работа с Poetry

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

В Poetry 1.x:

poetry shell

В Poetry 2.x: В версии 2.0.0 и выше команда poetry shell не доступна по умолчанию. Используйте один из следующих методов:

# Рекомендуемый способ: активация окружения
poetry env activate

# Альтернатива: установка плагина shell
poetry self add poetry-plugin-shell
poetry shell

# Или напрямую активируйте окружение
source .venv/bin/activate    # Linux/macOS
.venv\Scripts\activate.bat   # Windows cmd
.venv\Scripts\Activate.ps1   # Windows PowerShell

📘 Подробнее в документации: Poetry: Activating the environment

Запуск команд в виртуальном окружении

poetry run <команда>

Примеры:

poetry run python src/main.py
poetry run pytest
poetry run ruff format

Управление зависимостями

Добавление основной зависимости:

poetry add <имя_пакета>

Добавление зависимости для разработки:

poetry add <имя_пакета> --dev

Обновление зависимостей:

poetry update

🔄 Pre-commit

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

  1. Проверьте, что pre-commit установлен:

    pre-commit --version

  2. Настройте git hook:

    pre-commit install

После настройки при каждом коммите будет автоматически запускаться проверка линтером и форматирование кода.

🪟 Установка на Windows

🔽 Способ 1: Установка с использованием WSL (рекомендуется)

1. Установка WSL

  1. Откройте PowerShell от имени администратора и выполните:

    wsl --install

  2. Перезагрузите компьютер и завершите настройку Ubuntu.

  3. Подробная инструкция доступна по ссылке: Установка и настройка WSL

2. Установка необходимого ПО

  1. Установите Docker Desktop:

    # Скачайте и установите с официального сайта:
https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe

  2. Установите VS Code с расширением Remote - WSL.

  3. Установите Make в WSL:

    sudo apt update
sudo apt install make

  4. Установите Poetry в WSL:

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

    Альтернативные способы установки Poetry:

    Через pip:

    pip install poetry==1.7.1

    Через apt (если pip недоступен):

    sudo apt update
sudo apt install python3-pip
pip install poetry==1.7.1

    Проверка установки:

    poetry --version

    Настройка Poetry:

    poetry config virtualenvs.in-project true

3. Клонирование и настройка проекта

  1. Клонируйте репозиторий:

    git clone git@github.com:Studio-Yandex-Practicum/Tabit.git
cd Tabit

  2. Настройте Poetry:

    poetry config virtualenvs.in-project true
poetry install

4. Запуск проекта

  1. Активируйте виртуальное окружение:

    source .venv/bin/activate
# или
poetry shell

  2. Запустите приложение:

    make up                 # Запуск контейнера с БД

# Если миграции уже существуют:
make migration-apply    # Применение существующих миграций

# Если это первая инициализация:
make db-init            # Создание и применение начальных миграций

make create-superuser   # Создание суперпользователя
make fill-db            # Заполнение тестовыми данными
make run                # Запуск приложения
🔽 Способ 2: Установка на чистом Windows

1. Установка необходимого ПО

  1. Установите Chocolatey (менеджер пакетов для Windows):

    Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

  2. Установите Make:

    choco install make

  3. Установите Docker Desktop:

    # Скачайте и установите с официального сайта:
https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe

  4. Установите Python:

    # Скачайте и установите с официального сайта:
https://www.python.org/downloads/

  5. Установите Poetry: Выберите один из способов:

    Через pip:

    pip install poetry==1.7.1

    Через PowerShell:

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

    Проверка установки:

    poetry --version

    Настройка Poetry:

    poetry config virtualenvs.in-project true

2. Клонирование и настройка проекта

  1. Клонируйте репозиторий:

    git clone git@github.com:Studio-Yandex-Practicum/Tabit.git
cd Tabit

  2. Настройте Poetry:

    poetry config virtualenvs.in-project true
poetry install

3. Запуск проекта

  1. Активируйте виртуальное окружение:

    .venv\Scripts\activate.bat   # для cmd
.venv\Scripts\Activate.ps1   # для PowerShell

  2. Запустите приложение:

    make up                 # Запуск контейнера с БД

# Если миграции уже существуют:
make migration-apply    # Применение существующих миграций

# Если это первая инициализация:
make db-init            # Создание и применение начальных миграций

make create-superuser   # Создание суперпользователя
make fill-db            # Заполнение тестовыми данными
make run                # Запуск приложения

⚠️ Примечание: На чистом Windows могут возникнуть проблемы совместимости. Если столкнетесь с ошибками, рекомендуется перейти на WSL.

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

Настройка окружения

Для работы с базой данных создайте файл .env в корне проекта на уровне с директорией src.

Пример всех необходимых параметров можно найти в файле .env.example.

Пример содержимого .env:

# Настройки БД
POSTGRES_USER=warlock                     # Имя пользователя БД
POSTGRES_PASSWORD=zTudS8LBSquBMwvS3ky5    # Пароль к БД
POSTGRES_DB=tabit                         # Название БД
DB_PORT=5432                              # Порт для подключения к БД
DB_TYPE=postgresql                        # Тип базы данных
DB_API=asyncpg                            # API для работы с БД
DB_HOST=localhost                         # Хост для подключения к БД

📊 ERD модель данных

Актуальная ER-диаграмма базы данных доступна по ссылке

🔍 DBeaver

🔽 Подключение к БД через DBeaver
  1. Скачайте и установите DBeaver
  2. Создайте новое подключение (Ctrl+Shift+N)
  3. Выберите PostgreSQL
  4. Введите параметры подключения:
    • Хост: localhost
    • Порт: 5433 (или порт, указанный в .env)
    • База данных: tabit (или имя, указанное в .env)
    • Пользователь: warlock (или имя, указанное в .env)
    • Пароль: (указанный в .env)
  5. Нажмите "Тест соединения", затем "Готово"

🔍 pgAdmin

🔽 Работа с pgAdmin

pgAdmin — веб-интерфейс для управления PostgreSQL. В проекте доступен через контейнер Docker по адресу http://localhost:5600/

Настройка pgAdmin

  1. Добавьте в .env файл переменные:

    PGADMIN_DEFAULT_EMAIL=admin@email.com
PGADMIN_DEFAULT_PASSWORD=admin

  2. Запустите контейнер с pgAdmin:

    make up-pgadmin

    или

    docker compose -f infra/local/docker-compose.local.yaml --profile pgadmin up -d

  3. Откройте в браузере http://localhost:5600/

⚠️ Важно: Инициализация pgAdmin может занять до 8 минут (особенно на HDD).

Управление pgAdmin

Остановка контейнеров:

make down-pgadmin

или

docker compose -f infra/local/docker-compose.local.yaml --profile '*' down

Удаление контейнеров и томов:

make down-pgadmin-volumes

или

docker compose -f infra/local/docker-compose.local.yaml --profile '*' down -v

Дополнительные сведения о pgAdmin

Инструмент для взаимодействия с БД PostgreSQL, альтернатива DBeaver. Вариация в данном проекте работает через Docker-контейнер и доступна в браузере по ссылке http://localhost:5600/ или http://127.0.0.1:5600/. Полная документация доступна по ссылке: https://www.pgadmin.org/docs/pgadmin4/8.14/index.html

В контейнер монтируются:

  • servers.json - файл с данными для подключения к БД;
  • config_local.py - настройки для pgAdmin. Заменяют параметры, описанные в config.py внутри контейнера (подробнее: https://www.pgadmin.org/docs/pgadmin4/latest/config_py.html#config-py);
  • .pgpass - файл-пароль для подключения к БД;
  • create-admin-folder.sh - bash-скрипт для создания внутри контейнера необходимой папки и переноса туда .pgpass.

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

Достаточно в файл с переменными окружения .env добавить две переменных: PGADMIN_DEFAULT_EMAIL и PGADMIN_DEFAULT_PASSWORD, почта и пароль автоматически создаваемого админа соответственно (см. .env.example).

Особенности работы с pgAdmin

  • Полная инициализация pgAdmin может занимать много времени. На ноутбуке с HDD процесс занимал 8 минут. С SSD должно быть быстрее.
  • В процессе инициализации для первого админа создаётся автоматическое подключение к БД, данные для подключения описаны в файле servers.json. Благодаря файлу .pgpass пропадает необходимость вводить пароль для подключения.
  • Первый админ может создавать других пользователей с помощью User Management (меню в правом верхнем углу). Однако для таких пользователей подключение к БД нужно настраивать отдельно уже в интерфейсе системы.

👨‍💻 Разработка

🔄 Правила работы с git

🔽 Git-процесс в проекте

Основные ветки

  • master — production-ready код, используется для CI/CD
  • dev — предрелизная ветка с рабочим и выверенным кодом

Создание новых веток

  • Новые ветки всегда создаются от ветки dev
  • Названия веток:
    • feature/название-функционала — для нового функционала
    • bugfix/название-багфикса — для исправления ошибок

Процесс работы

  1. Создайте новую ветку от dev
  2. Внесите необходимые изменения
  3. Отправьте ветку в репозиторий
  4. Откройте Pull Request в ветку dev
  5. Добавьте ссылку на PR в соответствующую задачу в Kaiten

📝 Логирование

🔽 Система логирования

В проекте доступны два типа логирования:

  • Автоматическое логирование запросов через middleware
  • Ручное логирование через функцию logger

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

  1. Импортируйте логгер:

    from src.core.config.logging import logger

  2. Добавьте логи нужного уровня:

    logger.trace('Трассировочное сообщение')
logger.debug('Отладочное сообщение')
logger.info('Информационное сообщение')
logger.success('Сообщение об успехе')
logger.warning('Предупреждение')
logger.error('Сообщение об ошибке')
logger.critical('Критическая ошибка')

Настройка уровня логирования

Уровень логирования задается в .env переменной LOG_LEVEL. Доступные уровни:

  • TRACE
  • DEBUG
  • INFO
  • SUCCESS
  • WARNING
  • ERROR
  • CRITICAL

🧹 Линтеры

🔽 Проверка качества кода

В проекте используется Ruff для форматирования и проверки кода.

Основные настройки

  • Максимальная длина строки: 99 символов
  • Исключены из проверки: директории "alembic"
  • Проверки: "E" (ошибки), "F" (предупреждения), "I" (импорты)
  • Стиль строк: одинарные кавычки
  • Импорты: с учетом внутренних модулей src

Запуск проверки

poetry run ruff check .

Автоматическое форматирование

poetry run ruff format .

🔄 CI/CD и деплой

⚙️ GitHub Actions Workflows

В проекте настроены следующие автоматизированные процессы:

Workflow Описание Триггер
build_and_push.yaml Сборка и публикация образа Docker При необходимости
pytest.yaml Запуск тестов Push в репозиторий
ruff.yml Проверка кода линтерами Push, Pull Request
stage_deploy.yaml Деплой на Stage-окружение Push в определенную ветку

🐳 Инфраструктура Docker

🔽 Конфигурации Docker

Локальное окружение

  1. Только база данных

    make up              # Запуск

  2. База данных с pgAdmin

    make up-pgadmin      # Запуск

  3. Полное окружение

    make up-dc           # Запуск

  4. Общие команды

    make logs            # Просмотр логов
make down            # Остановка
make clean-volumes   # Остановка и полный сброс данных

Stage окружение

Конфигурация для Stage расположена в директории infra/stage:

  • docker-compose.stage.yaml — конфигурация Docker Compose
  • stage.Dockerfile — Dockerfile для сборки образа
  • tabit.service — Systemd-сервис для запуска на сервере

🚀 Деплой на Stage

🔽 Процесс деплоя

Деплой на Stage-окружение выполняется через GitHub Action workflow stage_deploy.yaml:

  1. Сборка Docker-образа
  2. Публикация образа в GitHub Container Registry
  3. Подключение к stage-серверу по SSH
  4. Загрузка конфигурационных файлов
  5. Запуск/перезапуск приложения через Systemd

Настройка секретов

Для работы деплоя необходимы следующие секреты в репозитории GitHub:

  • STAGE_HOST — хост stage-сервера
  • STAGE_SSH_KEY — приватный SSH-ключ
  • STAGE_SSH_USER — пользователь для SSH
  • STAGE_SSH_PASSWORD — пароль для SSH (если используется)

▶️ Запуск приложения

💻 Запуск приложения из командной строки 

python src/main.py [опции]

Поддерживаемые опции:

  • --reload или -r — отслеживание изменений в коде
  • --host или -h — указание хоста (по умолчанию 127.0.0.1)
  • --port или -p — указание порта (по умолчанию 8000)
  • --create-superuser или -c — создание суперпользователя

Пример:

python src/main.py -r -h 127.0.0.1 -p 1234

👤 Создать автоматически суперпользователя

  1. Заполните .env параметрами (примеры из .env.example):
FIRST_SUPERUSER_EMAIL=yandex@yandex.ru    # Почта
FIRST_SUPERUSER_PASSWORD=Password123      # Пароль (Латинские символов в обоих регистрах, числа, минимальная длина 8 символов)
FIRST_SUPERUSER_NAME=Ип                   # Имя
FIRST_SUPERUSER_SURNAME=Ман               # Фамилия
  1. Запустите:
python src/main.py -c

или

make create-superuser

🐞 Запуск контейнеров локально для отладки CI/CD

🔽 Локальное тестирование CI/CD

1. Настройка окружения

Создайте файл .env в корне проекта с необходимыми переменными (см. .env.example)

2. Запуск контейнеров

make up-dc

3. Проверка логов

make logs

4. Применение миграций

make migration-apply-dc

5. Наполнение тестовыми данными

make fill-db-dc

6. Создание супер пользователя (параметры в .env FIRST_SUPERUSER_EMAIL FIRST_SUPERUSER_PASSWORD )

make create-superuser-dc

7. Остановка контейнеров

make down

8. Остановка всех контейнеров и удаление томов

make clean-volumes

Особенности отладки CI/CD

  • Корректно завершает работу всех сервисов.
  • Очищает используемые контейнеры, но сохраняет данные в volume-ах.

После этих шагов можно быть уверенным, что CI/CD собирает проект корректно.

📋 Makefile команды

🔽 Docker Compose команды
Команда Описание
make up Запуск контейнера с БД
make up-pgadmin Запуск контейнеров с БД и pgAdmin
make up-dc Запуск полного окружения в контейнерах
make logs Вывод логов всех контейнеров
make down Остановка и удаление контейнеров
make clean-volumes Остановка контейнеров и удаление томов
🔽 Миграции и база данных
Команда Описание
make migration-init Создание первичной миграции с автогенерацией
make migration-auto m='commit' Создание миграции с указанным именем
make migration-empty m='commit' Создание пустой миграции
make migration-apply Применение всех миграций
make migration-apply-dc Выполнение миграций в контейнере
make migration-rollback Откат последней миграции
make db-reset Сброс базы и применение миграций
make db-init Запуск контейнеров и создание структуры БД
🔽 Запуск и тестовые данные
Команда Описание
make run Запуск приложения с Uvicorn на порту 8000
make create-superuser Создание суперпользователя
make fill-db Заполнение БД всеми тестовыми данными
make fill-companies Создание тестовых компаний
make fill-company-users Создание тестовых пользователей компаний
make fill-tabit-admin-users Создание тестовых администраторов
make fill-company-departments Создание тестовых отделов
make fill-license-type Создание тестовых типов лицензий
make fill-problems Создание тестовых проблем
make fill-message-feeds Создание тестовых лент сообщений
make fill-voting-feeds Создание тестовых вариантов голосования
make fill-voting-by-user Создание тестовых голосований
make fill-tasks Создание тестовых задач
make fill-comments Создание тестовых комментариев
make fill-tags Создание тестовых тэгов

🧪 Тестирование

Тесты используют базу данных PostgreSQL, которая автоматически разворачивается в контейнере перед запуском тестов и удаляется после их выполнения. Не нужно запускать контейнер вручную — pytest сделает это сам!

🔽 Как запустить тесты?

  1. Добавьте переменные тестовой базы данных в .env (если их нет):

    TEST_POSTGRES_USER=test_user
TEST_POSTGRES_PASSWORD=test_password
TEST_POSTGRES_HOST=localhost
TEST_POSTGRES_PORT=5433
TEST_POSTGRES_DB=test_db

    📌 Эти переменные используются для автоматического подключения к тестовой БД в контейнере.

  2. Убедитесь, что у вас установлен pytest:

    poetry add pytest --dev

  3. Запустите тесты:

    pytest -v

  4. Если хотите остановить тестирование при первой ошибке, используйте флаг -x:

    pytest -x -v

    Это ускоряет отладку, останавливая тесты сразу при первой неудаче.

  5. Запуск только последних упавших тестов (--lf):

    pytest --lf -v

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

  6. Запуск тестов в том же порядке, начиная с упавших (--ff):

    pytest --ff -v

    📌 Эта команда запустит тесты в том же порядке, что и в предыдущем запуске, начиная с упавших.

🔽 Что делать, если контейнер завис?

Если тесты не запускаются из-за проблем с контейнером, удалите его вручную:

docker-compose -f infra/docker-compose.test-db.yaml down -v

Эта команда остановит и полностью удалит контейнер с тестовой базой, включая все его данные. После этого можно запустить тесты заново.

🔽 Как работают тесты?

  1. Перед запуском тестов pytest сам поднимает контейнер с PostgreSQL:

    • Контейнер создаёт отдельную тестовую БД, чтобы не затронуть основную.
    • После поднятия контейнера происходит ожидание готовности БД.

  2. При запуске тестов pytest загружает переменные окружения из pytest.ini, включая параметры подключения к тестовой БД.

  3. После завершения тестов контейнер с БД автоматически удаляется.

📌 Важно: тестовая БД создаётся в отдельном контейнере и не влияет на основную базу данных. Теперь тесты полностью автоматизированы и изолированы! 🚀

❓ Часто встречающиеся ошибки

🔽 Конфликт портов PostgreSQL в WSL и Docker

При использовании PostgreSQL одновременно в WSL и Docker-контейнерах может возникнуть конфликт портов, если оба сервиса пытаются использовать порт 5432 (по умолчанию для PostgreSQL).

Симптомы:

  • Ошибка при запуске контейнера: Bind for 0.0.0.0:5432 failed: port is already allocated
  • Невозможно подключиться к базе данных
  • Невозможно применить миграции в контейнере с БД
  • Сервис PostgreSQL в WSL или Docker не запускается

Решение:

  1. Проверка занятых портов:

    sudo netstat -tuln | grep 5432

  2. Вариант 1: Остановить PostgreSQL в WSL Если PostgreSQL в WSL не нужен, остановите его:

    sudo service postgresql stop

  3. Вариант 2: Изменить порт в Docker Если нужно использовать оба сервиса, измените порт для Docker-контейнера:

    • В файле .env измените значение DB_PORT на свободный порт (например, 5433)
    • Перезапустите контейнеры

  4. Вариант 3: Изменить порт в WSL Если нужно использовать PostgreSQL в WSL, измените его порт:

    • Откройте конфигурационный файл PostgreSQL: 
      sudo nano /etc/postgresql/<версия>/main/postgresql.conf
    • Найдите строку port = 5432 и измените на свободный порт
    • Перезапустите PostgreSQL: 
      sudo service postgresql restart

Профилактика:

  • Всегда проверяйте занятые порты перед запуском контейнеров
  • Используйте разные порты для WSL и Docker, если оба сервиса нужны одновременно
  • Убедитесь, что в .env указан правильный порт для подключения к базе данных
🔽 Конфликт имён контейнеров Docker

При обновлени репозитория или работе с несколькими его копиями может возникнуть пересечение имён контейнеров при запуске

Симптомы:

Сообщение в консоли:

Error response from daemon: Conflict. The container name "/postgres_local" is already in use by container...

Решение:

  1. Прорерить запущенные контейнеры
docker ps
  1. Если обнаружены лишние контейнеры - остановить и удалить их вручную Пример:
docker stop postgres_local
docker remove  postgres_local
  1. Если обнаруженные контейнеры нужны - изменить название контейнеров в текущем локальном запуске чепез .env Пример:
APP_CONTAINER_NAME=tabit_new
DB_CONTAINER_NAME=postgres_new
PGADMIN_CONTAINER_NAME=pgadmin_new
  1. Предпринять новую попытку запуска

About

Online service for HR and company owners.

tabit.website/

Resources

Readme
Activity
Custom properties

Stars

8 stars

Watchers

3 watching

Forks

2 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages