Uniscope project guideline

Get started

General

1. Установите pnpm версии, соответствующей указанной в package.json в корне репозитория.
2. Установите turborepo версии, соответствующей указанной в base.dockerfile в корне репозитория.
3. Установите пакеты зависимостей всего репозитория коммандой pnpm install.
4. Установите mkcert, перейдите в директорию ./apps/proxy/ssl и выполните команду mkcert -install. После этого создайте сертификаты для localhost командой mkcert localhost. Гайд: https://web.dev/how-to-use-local-https/

Важно! Работа в режиме разработки над конкретным модулем гарантирована только при запуске команд через turborepo.

Некоторые модули системы непосредственно зависят от других, а потому их запуск является сложной комплексной задачей, которая решается при помощи turborepo. Например: бекенд запускается только вместе с базой данных, а фронтенд - только вместе с бекендом. Используйте команды вида: turbo run <script>, где <script> - имя команды.

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

1. Репозиторий

Репозиторий проекта включает в себя основные директории:

• apps - директория, в которой располагаются все глобальные модули продукта - бекенд, фронтенд, база данных и т.д. Каждый модуль в кластерном режиме обычно имеет собственный контейнер, запускаемый через docker-compose.prod.yml. Модули, запускаемые исключительно в контейнере, также имеют docker-compose.dev.yml для запуска в дев режиме.
• packages - директория, в которой располагаются все локальные модули продукта - библиотеки, общие для различных глобальных модулей. Не запускаются напрямую и являются переиспользованием кода между глобальными модулями. Также поощеряется вынос стандартных компонентов в отдельные пакеты, с целью дальнейшего открытия их исходного кода.
• business - директория, в которой располагаются все полезные с точки зрения бизнеса модули продукта - боты, агрегаторы, парсеры и т.д. При этом непосредственно в системе они не используются, а запускаются по мере необходимости как вспомогательные инструменты.
• prototypes - директория хранения прототипов UI, созданных в программе Axure.

2. PNPM

В качестве менеджера пакетов используется PNPM. Он позволяет ускорить установку зависимостей, а также уменьшить размер установленных пакетов. В репозитории используется политика воркспейсов. Вы должны самостоятельно установить нужную версию pnpm (указана в глобальном package.json) в свое глобальное окружение для работы в репозитории.

3. Turborepo

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

Turborepo имеет весьма специфичный способ определения задач в монорепозитории. С ним вы должны ознокомится самостоятельно, но в целом, задачи, свойственные КАЖДОМУ воркспейсу монорепы описываются в файле turbo.json в корне репозитория, также там описываются задачи свойственные ИСКЛЮЧИТЕЛЬНО самой монорепе (описываются через //), а в локальном файле turbo.json для конкретного воркспейса описываются специфические задачи этого воркспейса и дополняются общие задачи, раннее описанные в глобальном конфиге.

Turborepo отвечает за ВЕСЬ спектр задач, исполняемых в монорепе (lint, test, e.t.c.), кроме сборки продакшен образов, так как они должны собираться на голой машине с докером не имея под рукой никаких зависимостей (Node.js/pnpm/turbo).

При этом Turborepo не отвечает за зависимости между макрозадачами (например, запуск билда зависит от тестов и линта). Он отвечает только за те зависимости, которые нужны для исполнения самой макрозадачи непосредственно. Зависимостями между макрозадачами занимается GitLab CI/CD.

4. Environments

В репозитории используется 3 способа запуска проекта:

• developent - для разработки в режиме hot-reload. Запускаете все необходимые сервисы самостоятельно. Сервисы, имеющие внутренние способы запуска в режиме разработки запускаются при помощи соответствующих внутренних команд (frontend, backend). Иные сервисы, поставляемые исключително путем docker контейнеров запускаются при помощи соответствующих docker-compose.dev.yml (database).
• local - запуск продакшен кластера системы на локальной машине. Осуществляется путем запуска глобального docker-compose.yml с env переменными из файла .env.local-prod. Для корректной работы необходимо создать ssl сертификаты для localhost и установить mkcert как доверенный CA согласно гайду. Сертификаты поместить по пути ./apps/proxy/ssl.
  Выполняется при помощи двух команд:
  • pnpm run compose:dev:build - сборка образов для локального запуска
  • pnpm run compose:dev:up / pnpm run compose:dev:restart - запуск сервисов
• production - запуск продакшен кластера системы на удаленной машине. Осуществляется путем запуска глобального docker-compose.yml с env переменными из файла .env.production и только внутри пайплайна gitlab.ci, описанного ниже.

5. GitLab CI/CD

В качестве инструмента для автоматизации процесса разработки используется GitLab CI/CD. Он позволяет автоматизировать процесс сборки, тестирования, деплоя и т.п. в репозитории. Именно в нем указывается зависимость между макрозадачами (например, запуск билда зависит от тестов и линта), а также описывается вся логика работы CI/CD.

• Все макрозадачи выполняются в контейнере GitLab раннера с лейблом build с образом ноды используемой нами версии (см. package.json). Все сбилженые контейнеры отправляются в GitLab Docker Registry.
• Развертка образов на сервере осуществляется в shell раннере с тегом deploy, развернутом на этой же продакшен машине. Пул образов осуществляется непосредственно из ранее упомянутого GitLab Docker Registry.

Backend

Для знакомства с модулем смотреть соответствующий гайд.

Frontend

Для знакомства с модулем смотреть соответствующий гайд.

Hardend

Для знакомства с модулем смотреть соответствующий гайд.