SWAP Application Platform

SWAP (Smart Workforce Application Platform) - это система по поиску и управлению рабочими местами сотрудников.

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

Бэкэнд

• dockerscripts - вспомогательные docker-скрипты для сборки образа проекта бэкэнда. Используются только при сборке образа и только в Docker.
• docs - общая интерактиваная документация системы SWAP
• etc - каталог с конфигурацией для сторонних утилит и приложений (nginx, uwsgi и т.д.)
• scripts - каталог с вспомогательными скриптами для разработки и публикации системы.
• sources - каталог с программной логикой сервисов системы
• core - корневой(ые) сервис(ы) системы, на которых она основывается - авторизация, уведомления и т.д.
• domain - вспомогательные и дополнительные сервисы системы, которые так же используются в системе, но которые при желании можно отключить, не потеряв при этом в функциональности.
• justfile - Makefile-подобный файл с рецептами.
• *.env.example - примеры .env-конфигураций проекта. Используйте их как отправную точку для конфигурации проекта.

Модули (они же сервисы)

Важно! Соблюдайте правила именования каталогов с сервисами! Весь путь до каталога с сервисом (считается, что в корне каталога сервиса находятся .env и justfile файлы) должен содержать в себе только [a-z0-9_] символы! Пожалуйста, не используйте никакие другие символы, кроме английской раскладки в нижнем регистре, цифр от 0 до 9 и символа нижнего подчеркивания!

Ядро

• core - sources/core/swap_core - ядро системы

Дополнительные

• marketplace - sources/domain/swap_marketplace - рынок

Установка

Совет: устанавливайте систему в чистую виртуалку/контейнер, чтобы не попортить системные зависимости и запускать проект в изолированной от основной системы среде!

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

• python3 - чем свежее версия, тем лучше.

  Моя версия - 3.13.3.

  Проверить свою: python3 --version

• git - аналогично.

  Моя версия - 2.39.5.

  Проверить свою: git --version

• rsync - аналогично, если вы собираетесь деплоить вручную на стенды.

  Моя версия - 3.4.1 (protocol version 32).

• uwsgi - лучше собрать с официального репозитория по последнему тегу, например git clone https://github.com/unbit/uwsgi -b 2.0.28

  Моя версия - 2.0.28.

  Проверить свою: uwsgi --version

• docker (если очень смелые, можете попробовать podman, я не пробовал ._.)

  Моя версия - Docker version 27.4.1.

  Проверить свою: docker --version

• docker compose (именно тот, что с пробелом - более свежая версия, docker-compose - устаревшая версия!)

  Моя версия - Docker Compose version v2.28.1.

  Проверить свою: docker compose version

• just - аналог make для Makefiles, но с бОльшим набором опций, скачать можно бесплатно с just.systems

  Рекомендую выбрать способ установки с PyPI.

  pipx install rust-just. Если нет pipx - pip install pipx.

  Моя версия - just 1.30.1.

  Проверить свою - just --version

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

Настройка перед запуском

Каждый модуль должен быть настроен перед запуском. Покажу пример для модуля marketplace, аналогичная процедура должна быть и для других модулей.

# Заходим в репо с модулем
cd sources/domain/swap_marketplace/swap_marketplace_backend
# Запускаем команды модуля
just bootstrap
# Следуем инструкциям и открываем файл .env любым текстовым редактором, например nano
nano .env

Заполняем следующие переменные в .env (только те, которые незаполнены)

DATABASE_URL="postgres://postgres:supersecretpassword@localhost:5432/swap-dev"
DJANGO_DEBUG="True"
DJANGO_CONFIGURATION="Dev"
DJANGO_SECRET_KEY="{тут будет большой сгенерированный ключ, не трогаем его и никому не показываем}"

Q: Что будет, если сломать/поменять ключ (DJANGO_SECRET_KEY)?

Если записей в БД ещё нет, то не будет ничего. Однако если вы уже зарегистрировались в системе (именно локально), и каким-то образом потеряли/поломали ключ, то вы не сможете войти в систему. По сути этот ключ используется для шифрования сессии пользователя.

Если это всё-таки случилось и вы уже зарегистрировались в системе локально:

1. запускаем .venv/bin/python3 manage.py flushdb и следуем инструкциям команды.
2. затем пересоздаём суперпользователя (именно в проекте, не в самой системе/контейнере/виртуалке!) командой .venv/bin/python3 manage.py createsuperuser и вводим заново email и пароль вашего пользователя

Сохраняем файл и запускаем следующие команды:

# Обязательно: для применения миграций к БД.
just migrate
# Опционально: если требуется запустить только один модуль, отдельно от всей системы.
# Однако я рекомендую запускать из корня системы весь проект.
just run

Запуск

Специально для вашего (в основном, для моего) удобства был написан justfile, в котором находятся алиасы всех частоиспользуемых команд.

Запуск всего проекта (все модули системы)

Я рекомендую запускать из корня системы весь проект. Не так удобно при отладке, зато все сервисы работают и взаимодействуют друг с другом.

# если вы не в корне проекта - переходите туда
# (проверьте текущую директорию на наличие файла `docker-compose.yml`, если он присутствует - вы в корне проекта).
pwd  # должно быть /home/{your_user}/{your_secret_path}/swap
ls docker-compose.yml  # должен вывести название файла, а не ошибку.
# запускаем сервисы из docker-compose - s3 хранилище, valkey (он же форк redis), postgres и сам проект swap
just up

Внимательно смотрим логи, которые выводит uwsgi.

just logs backend

Если нигде не выскакивает ошибок и uwsgi не начинает бешено перезагружать сервисы - поздравляю, мы успешно запустились!

Запуск конкретного модуля системы

Однако если возникает потребность запустить непосредственно определённый модуль системы (например, marketplace), то лучше сделать так:

# переходим в каталог с этим самым модулем. Корень (корневой каталог) модуля находится там, где лежит justfile
cd sources/domain/swap_marketplace/swap_marketplace_backend
# запускаем модуль
just run

Всё! Если модуль не плюётся ошибками в консоль, он успешно запустился!