iac/apps/projects/CONFIGURATION.md

Конфигурация проекта projects-frontend

Документ описывает, как конфигурируется микрофронтенд projects-frontend: переменные сборки, способы запуска, параметры Docker/nginx, Helm-чарта и CI.

Способы конфигурирования

projects-frontend — это клиентский микрофронтенд (React 17 + MobX, сборка Webpack 5, Module Federation). У приложения нет runtime-конфигурации и файла .env: всё поведение, зависящее от окружения, определяется на этапе сборки одной переменной BUILD_ENV.

Разбор выполняется в configWebpack/config/build.config.ts (extractBuildOptions): значение process.env.BUILD_ENV (одно из local / stage / prod / preprod / contour, по умолчанию prod) определяет режим сборки (development/production) и «endpoint». Полученный endPoint через DefinePlugin (configWebpack/buildPlugins.ts) подставляется в бандл как глобальная константа __ENDPOINT__:

new DefinePlugin({ __ENDPOINT__: JSON.stringify(endPoint) })

Константа __ENDPOINT__ используется в рантайме бандла для выбора:

• карты хостов API — src/shared/api/http-service.ts (const endpoint = (__ENDPOINT__ as TypeEnvironment) || "prod") поверх src/shared/api/hosts.ts;
• URL удалённого модуля timeline — src/widgets/remote-timeline/ui/timelineProxy.tsx;
• локального провайдера разработки — src/app/bootstrap.tsx (__ENDPOINT__ === "local" ? <LocalDevProvider /> : <div />).

Отдельного конфиг-файла (yaml/env) у приложения нет.

Переменные сборки и запуска

Переменная	Где используется	Значение по умолчанию	Назначение
BUILD_ENV	webpack.config.ts, configWebpack/config/build.config.ts, Dockerfile (build-arg)	prod	Целевое окружение сборки: local/stage/prod/preprod/contour. Определяет режим (development/production), карту хостов и URL удалённых модулей
NPM_NEXUS_TOKEN	.npmrc, Dockerfile (build-arg)	—	Токен доступа к приватному npm-реестру Nexus (https://nexus.infra.sarex.io/repository/npm/) для установки пакетов @sarex-team/*
PORT	webpack.config.ts	9001	Порт dev-сервера Webpack

Версия Node фиксирована в .nvmrc — v16.0.0. Приватный реестр и авторизация заданы в .npmrc:

@sarex-team:registry=https://nexus.infra.sarex.io/repository/npm/
//nexus.infra.sarex.io/repository/npm/:_authToken=${NPM_NEXUS_TOKEN}

npm-скрипты (package.json)

Команда	Действие
npm run dev	Локальная разработка: BUILD_ENV=local webpack serve --config webpack.config.ts
npm run build-module	Сборка модуля: webpack --config webpack.config.ts (окружение — из BUILD_ENV)
npm run build:start	Раздача собранного бандла: serve -s ./dist -l 9001
npm run lint	Форматирование Prettier: npx prettier --write .

Сборка Webpack и Module Federation

Точка входа — src/app/index.ts (webpack.config.ts). Для всех окружений, кроме local, добавляется ModuleFederationPlugin:

• name: srx_projects;
• filename: module/remoteEntry.js;
• exposes: ./ProjectsPage → ./src/app/App.tsx;
• shared (singleton, requiredVersion: false): react, react-dom, @material-ui/core, @sarex-team/sdk-js.

Плагины (configWebpack/buildPlugins.ts): HtmlWebpackPlugin, DefinePlugin. В режиме local дополнительно ProgressPlugin, ForkTsCheckerWebpackPlugin, ReactRefreshWebpackPlugin; вне local — MiniCssExtractPlugin (хеши в именах файлов).

Dev-сервер (configWebpack/buildDevServer.ts)

HTTPS, порт 9001, historyApiFallback, hot. Прокси на stage-окружение с pathRewrite:

Префикс	Target
/sarex-backend	https://stage.sarex.io
/sarex-gateway	https://stage-api.sarex.io/gateway
/sarex-documentations	https://stage-api.sarex.io/documentations
/sarex-api	https://stage-api.sarex.io

Заголовки CORS dev-сервера разрешают любой origin, методы GET, POST, PUT, DELETE, PATCH, OPTIONS и заголовки X-Requested-With, content-type, Authorization.

Docker

Многоступенчатая сборка (Dockerfile):

1. Стадия сборки (node:16): установка зависимостей (npm i с NPM_NEXUS_TOKEN), npm run lint, BUILD_ENV=$BUILD_ENV npm run build-module → dist.
2. Стадия раздачи (nginx:1.19.6): копирование dist в /dist и nginx/nginx.conf в /etc/nginx/nginx.conf.

Build-args: BUILD_ENV, NPM_NEXUS_TOKEN.

nginx (nginx/nginx.conf)

Статика раздаётся с root /dist на порту 80. Особенности:

• location = /ping → возвращает 200 {"result": "ok"} (используется как liveness/readiness-проба);
• location = /module/remoteEntry.js → Cache-Control: no-store, no-cache, must-revalidate…, expires off (точка входа Module Federation не кешируется);
• gzip on, логи в stdout/stderr.

Helm-чарт (.helm)

Чарт projects-frontend (Chart.yaml, type: application, version: 0.1.0, appVersion: 1.16.0) разворачивает статику как Deployment + Service (templates/static.yaml) и публикует её через Istio VirtualService (templates/mesh-config.yaml).

Значения задаются в values-<env>.yaml (блок static):

Параметр	stage	preprod	production
static.host	stage-modules.sarex.io	modules.preprod.sarex.io	modules.sarex.io
static.replicas	1	2	2
static.path	/projects/static/	/projects/static/	/projects/static/
static.image	sarex/projects-frontend-static:latest	то же	то же
static.port / static.service_port	80 / 80	80 / 80	80 / 80
static.requests	memory: 100Mi, cpu: 100m	то же	то же
imagePullSecrets	dockerhub	dockerhub	dockerhub

Общее для всех окружений: static.name: projects-frontend-static, static.service_name: projects-frontend-static-service, static.version: stable. Пробы livenessProbe/readinessProbe бьют в /ping (templates/static.yaml).

VirtualService (templates/mesh-config.yaml): хост static.host, шлюз gateway/modules-gateway, матч по префиксу static.path (/projects/static/) с rewrite на /. Политика CORS: allowOrigins по регулярке (https://.*\.sarex\.io)|(https://localhost:.*), allowMethods: [GET, POST, PUT, PATCH, HEAD, DELETE], allowHeaders: [Authorization, Content-Type], maxAge: 24h.

CI/CD (.gitlab-ci.yml)

Пайплайн подключает общие шаблоны из generic/common-ci (universal-pipeline-*, common-security-scan, common-build) и переключает окружение по ветке/тегу через workflow.rules:

Условие	STAND	Namespace	BUILD_ENV
ветка master	preprod	projects-preprod	preprod
ветка stage	stage	projects-stage	stage
тег (CI_COMMIT_TAG)	prod	projects-prod	prod

Ключевые переменные пайплайна (общие для всех окружений): RELEASE_NAME/CHART_NAME = projects-frontend, IMAGE_PATH = static.image, HELM_SET_ARGS = --set static.image=${IMAGE_NAME}, BUILD_ARGS = --build-arg BUILD_ENV=<env> --build-arg NPM_NEXUS_TOKEN=${NPM_NEXUS_TOKEN}, DOCKERFILE_PATH = Dockerfile. Флаги этапов: ENABLE_LINTER (false), ENABLE_BUILD_CHART, ENABLE_BUILD_IMAGE, ENABLE_STATE_UPDATE, ENABLE_DEPLOY (true). CHART_VERSION задаётся как 0.0.1-<env>. Стадии: linter → test → unittest → prebuild-secscan → build → state-update → deploy.

Замечания и потенциальные проблемы

• Нет runtime-конфигурации. Всё, что зависит от окружения, «зашивается» в бандл на этапе сборки через BUILD_ENV/__ENDPOINT__. Пересборка под другое окружение обязательна — переопределить хосты в рантайме нельзя.
• Значение по умолчанию BUILD_ENV=prod. Если переменная не задана при сборке, собирается production-вариант (build.config.ts, webpack.config.ts, http-service.ts). Для локальной разработки нужно явно BUILD_ENV=local (скрипт npm run dev это делает).
• Окружение contour неполно сконфигурировано. Оно перечислено в build.config.ts и типах, но в src/shared/api/hosts.ts карта хостов для contour отсутствует, а URL удалённого модуля timeline для contour пуст (timelineProxy.tsx). Сборка с BUILD_ENV=contour не сможет разрешить хосты API.
• README не совпадает с package.json. В README.md указаны nvm use 16.0.0 и npm run start:local, однако скрипта start:local в package.json нет — локальный запуск выполняется командой npm run dev. .nvmrc фиксирует v16.0.0.
• Версии чарта расходятся. В Chart.yaml — version: 0.1.0 / appVersion: 1.16.0, тогда как в CI CHART_VERSION задаётся как 0.0.1-<env>. Значения не синхронизированы.
• Приватный реестр. Установка зависимостей требует валидный NPM_NEXUS_TOKEN (.npmrc); без него npm i (в т.ч. в Docker-сборке) завершится ошибкой авторизации.

Минимальный набор для локального запуска

1. nvm use (Node v16.0.0 из .nvmrc).
2. Экспортировать NPM_NEXUS_TOKEN (доступ к Nexus) и выполнить npm i.
3. npm run dev — соберёт с BUILD_ENV=local и поднимет HTTPS dev-сервер на https://localhost:9001 (запросы к backend проксируются на stage через /sarex-backend, /sarex-gateway, /sarex-documentations, /sarex-api).