Skip to content

Studio-Yandex-Practicum/Tabit

BranchesTags

Repository files navigation

Tabit

Оглавление

  1. О проекте
  2. Начало работы
  3. Работа с базой данных
  4. Разработка
  5. CI/CD и деплой
  6. Запуск приложения
  7. Справочник команд Makefile

О проекте

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

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 apply-migrations   # Применение существующих миграций

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

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/

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

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

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

  2. Установите и настройте Poetry:

    pip install poetry==1.7.1
poetry config virtualenvs.in-project true
poetry install

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# Настройки БД
POSTGRES_USER=warlock                     # Имя пользователя БД
POSTGRES_PASSWORD=zTudS8LBSquBMwvS3ky5    # Пароль к БД
POSTGRES_DB=tabit                         # Название БД
PORT_BD_POSTGRES=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/docker-compose.local-with-pgadmin.yaml up -d

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

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

Управление pgAdmin

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

make down-pgadmin

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

make down-pgadmin-volumes

Разработка

Правила работы с 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.logger 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     # Запуск
make down   # Остановка

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

    make up-pgadmin         # Запуск
make down-pgadmin       # Остановка

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

    make up-dc              # Запуск
make down-dc            # Остановка
make logs-dc            # Просмотр логов

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-dc

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

make migrate-dc

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

make down-dc

Makefile команды

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

About

Online service for HR and company owners.

tabit.website/

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

4 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 18

+ 4 contributors

Languages