iac/apps/stamp-verification/CONFIGURATION.md

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

Документ описывает, как конфигурируется и разворачивается модуль stamp-verification-frontend — публичная статическая страница проверки штампа (QR) на документе.

Что это за сервис

stamp-verification-frontend — это статический фронтенд (обычный HTML + ванильный JavaScript + moment.js), который раздаётся через nginx. По QR-коду со штампа на PDF пользователь попадает на страницу с параметрами ?id=<qrId>&page_number=<n>, страница запрашивает данные документа у backend-сервиса documentations и отображает информацию о версии, авторе, дате загрузки, статусе согласования и ссылке на документ в Sarex.

Ключевое отличие от backend-сервисов: у приложения нет разбора переменных окружения. Здесь нет pydantic-settings, нет .env, нет секций конфигурации. Всё «runtime»-поведение либо статично, либо определяется по хосту в браузере (window.location.host). Конфигурируется только сборка и деплой (Docker, Helm/universal-chart, GitLab CI).

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

Слой	Где задаётся	Что настраивает
Runtime (браузер)	static/js/index.js	Выбор базового URL API по window.location.host; параметры запроса берутся из query-строки (id, page_number, v)
Веб-сервер	nginx.conf	Порт прослушивания 8080, корень /dist, health-check GET /ping → 200 {"result": "ok"}, gzip, логи в stdout/stderr
Образ	Dockerfile	Базовый образ nginx:mainline-alpine-otel, копирование static/ и index.html в /dist, EXPOSE 8080
Helm	.helm/values.yaml, .helm/Chart.yaml	Значения чарта-зависимости universal-chart (deployment, image, service, imagePullSecrets)
CI/CD	.gitlab-ci.yml	Выбор окружения по ветке/тегу, имя релиза/чарта, HELM_SET_ARGS
IaC (kustomize)	iac/apps/stamp-verification/**	Namespace, Deployment, Service и оверлеи кластеров (этот репозиторий)

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

Runtime-поведение (static/js/index.js)

Скрипт выполняется на DOMContentLoaded. Логика:

• читает query-параметры: id (идентификатор QR), page_number, v (пока не используется);

• запрос выполняется только если заданы одновременно id и page_number;

• выбирает базовый URL API:

  window.location.host	Базовый URL API	Окружение
  stamp-verification.sarex.io	api.sarex.io	prod
  любой другой (напр. stamp-verification.stage.sarex.io)	stage-api.sarex.io	stage

• делает fetch GET https://<apiBaseUrl>/documentations/api/v1/public/qr/{id}/document_info?number_page={page_number} с mode: cors, credentials: include, cache: no-cache;

• по ответу заполняет поля страницы (название, версия, номер страницы, автор, дата загрузки), блок изменений (changelog), индикаторы актуальности/аннулирования версии, статус согласования и ссылку на документ.

Локаль дат — ru (moment.locale("ru")), формат отображения даты — DD.MM.YYYY / HH:mm.

Полный перечень внешних вызовов см. в ENDPOINTS.md, контракт эндпоинта — в openapi.yaml.

nginx (nginx.conf)

Параметр	Значение	Назначение
listen	8080	Порт HTTP
root	/dist	Корень статики (туда Dockerfile кладёт static/ и index.html)
location = /ping	return 200 '{"result": "ok"}'	Health-check для k8s-проб/балансировщика
access_log	/dev/stdout	Логи доступа в stdout
error_log	stderr warn	Логи ошибок в stderr
gzip	on	Сжатие ответов
expires	off	Без заголовков кеширования

Docker (Dockerfile, docker-compose.yml)

Образ на базе nginx:mainline-alpine-otel. Сборка копирует nginx.conf в /etc/nginx/nginx.conf, каталог static и index.html в /dist, выставляет права на /var и /run, объявляет EXPOSE 8080 и запускает nginx -g "daemon off;". Build-time аргументов нет (BUILD_ARGS="").

docker-compose.yml — только для локального прогона (image: sarex/landing:latest, публикует порт 8000:8000; обратите внимание, что nginx внутри слушает 8080 — маппинг в compose оставлен историческим).

Helm / universal-chart (.helm/)

Chart.yaml подключает зависимость universal-chart (oci://cr.yandex/crp3ccidau046kdj8g9q/charts, версия 0.1.7). Значения задаются в values.yaml под ключом universal-chart и разбиты по окружениям через суффиксы (_default, stage, preprod, production).

Ключ (universal-chart.services.frontend.*)	Значение (_default)	Назначение
deployment.enabled	true	Создавать Deployment
deployment.name	stamp-verification-frontend	Имя Deployment
deployment.port	8080	Порт контейнера
deployment.replicaCount	1	Число реплик
image.name	cr.yandex/crp3ccidau046kdj8g9q/stamp-verification-frontend:latest	Образ
image.pullPolicy	IfNotPresent	Политика загрузки образа
service.enabled	true	Создавать Service
service.name	frontend-service	Имя Service
service.port	8080 (в production — 80)	Порт сервиса
service.targetPort	8080	Целевой порт
service.type	ClusterIP	Тип сервиса
imagePullSecrets.name	dockerhub	Секрет для доступа к реестру

global.env (_default) выбирает активный набор значений по окружению.

CI/CD (.gitlab-ci.yml)

Пайплайн подключает общие шаблоны generic/common-ci (common-security-scan.yaml, universal-pipeline.yaml, ref apps-business). Общие переменные: SERVICE_NAME=stamp-verification-frontend, DOCKERFILE_PATH=Dockerfile, BUILD_ARGS="", CI_TRIGGER_SOURCE=app.

Окружение переключается правилами workflow.rules:

Условие	STAND	NAMESPACE	CHART_VERSION	K8S_HUSTLER_BRANCH
merge_request_event	—	—	—	ENABLE_BUILD_IMAGE="false" (только проверки, без сборки образа)
ветка stage	stage	documentations	0.0.1-stage	universal-chart-stage
ветка master	preprod	stamp-verification-preprod	0.0.1-preprod	universal-chart-preprod
тег (CI_COMMIT_TAG)	production	stamp-verification-prod	0.0.1-prod	universal-chart-production
иначе	when: never

Для каждого деплой-окружения HELM_SET_ARGS передаёт: образ (universal-chart.services.frontend.image.name.<env>=${IMAGE_NAME}), universal-chart.global.env=<env> и метаданные коммита (commitSha, gitlabUri, gitlabJobUrl, owner).

Инфраструктура (kustomize, этот репозиторий)

Каталог iac/apps/stamp-verification/ содержит kustomize-манифесты (альтернатива/дополнение к Helm-деплою из CI):

• base/namespace.yaml — namespace stamp-verification с istio-injection: enabled;
• base/deployment.yaml — Deployment frontend (образ cr.yandex/crp3ccidau046kdj8g9q/stamp-verification-frontend:<sha>, imagePullPolicy: IfNotPresent, containerPort: 80, requests cpu: 25m/memory: 100Mi, imagePullSecrets: regcred);
• base/service.yaml — Service frontend-service (ClusterIP, port: 80 → targetPort: 80);
• base/kustomization.yaml — сборка base (namespace + deployment + service);
• yc-k8s-test/kustomization.yaml — оверлей кластера (resources: ../base, патчи закомментированы);
• yc-k8s-test/replicas.yaml — заготовка патча реплик (replicas: 1).

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

• Захардкоженный JWT. В static/js/index.js в заголовок Authorization: Bearer … вшит истёкший (2023 г.) токен. Публичный эндпоинт /public/qr/... не должен требовать пользовательский токен — строку следует удалить. Держать секреты в статике недопустимо.
• Рассогласование портов. nginx и Helm/universal-chart используют порт 8080, а kustomize-манифесты в этом репозитории (base/deployment.yaml, base/service.yaml) — порт 80. Нужно привести к одному значению (образ слушает 8080), иначе проброс/пробы могут не сходиться.
• Дублирование деплоя. Приложение может разворачиваться и через Helm (CI, чарт universal-chart), и через kustomize (этот репозиторий). Следует зафиксировать единый источник истины, чтобы образ/порт/namespace не расходились.
• NAMESPACE для stage. На ветке stage деплой идёт в namespace documentations (общий), тогда как preprod/prod — в выделенные stamp-verification-*. Это осознанное решение или наследие — стоит проверить.
• Конфиг только по хосту. Выбор prod/stage жёстко завязан на строку stamp-verification.sarex.io. Любой новый прод-домен потребует правки кода, а не конфигурации.
• Mock-данные в бандле. В index.js присутствуют объекты mockData/mockChangeLog — тестовые данные, оставшиеся в продовом бандле. На поведение не влияют (не используются), но их стоит убрать.

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

Отдельная конфигурация не требуется — приложение статично:

# сборка и запуск образа
docker build -t stamp-verification-frontend .
docker run --rm -p 8080:8080 stamp-verification-frontend
# проверка
curl http://localhost:8080/ping        # {"result": "ok"}
# страница: http://localhost:8080/?id=<qrId>&page_number=1

Для реальных данных нужен доступный backend documentations (по умолчанию для не-prod хоста используется https://stage-api.sarex.io).