docs(registry): add Russian build runner and release evidence plan

2026-06-21 07:10:43 +03:00
parent 6861df9be4
commit f5e9c81c5b
12 changed files with 946 additions and 19 deletions
@@ -0,0 +1,114 @@
+# Build-runner setup runbook
+
+Статус: registry-readiness runbook. Команды предназначены для нового
+российского build-runner `awatch-build-01`. Runbook не меняет product runtime,
+API, UI или deployment behavior.
+
+## Базовая подготовка
+
+```bash
+hostnamectl set-hostname awatch-build-01
+apt update
+apt upgrade
+```
+
+## Базовые пакеты
+
+```bash
+apt install -y \
+  curl \
+  wget \
+  git \
+  jq \
+  ca-certificates \
+  gnupg \
+  build-essential \
+  pkg-config \
+  libssl-dev \
+  clang \
+  cmake \
+  protobuf-compiler \
+  nodejs \
+  npm \
+  python3 \
+  unzip \
+  tar \
+  rsync
+```
+
+`protobuf-compiler`, `nodejs` и `npm` нужны только если соответствующие
+components/checks используются в текущем release candidate. Если package policy
+организации требует другой способ установки, использовать корпоративный
+approved mirror/toolchain и зафиксировать это в release evidence.
+
+## Rust toolchain
+
+Вариант через rustup допустим только если он разрешен политикой владельца
+инфраструктуры:
+
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs -o /tmp/rustup-init.sh
+sh /tmp/rustup-init.sh
+```
+
+Альтернатива: установить Rust toolchain из корпоративного mirror/package
+repository и зафиксировать источник установки в release evidence. Скрипты
+репозитория не должны выполнять `curl | sh` и не должны сами устанавливать
+toolchain.
+
+## Проверка инструментов
+
+```bash
+rustc --version
+cargo --version
+git --version
+node --version
+npm --version
+jq --version
+```
+
+Если Node.js/npm не устанавливались, зафиксировать это как `skipped: tool not
+installed` для соответствующих smoke checks.
+
+## Пользователь build
+
+```bash
+useradd --create-home --shell /bin/bash build
+usermod -aG sudo build
+```
+
+Доступ должен быть key-based SSH. Пароли, токены, приватные ключи и cookies не
+хранить в репозитории.
+
+## Безопасная модель доступа
+
+- SSH key based access.
+- No secrets in repo.
+- GitHub tokens, Gitea tokens и SSH private keys только в environment variables
+  или protected files outside repo.
+- Protected files должны иметь ограниченные permissions и не попадать в
+  source archive.
+- Build scripts не должны менять remotes, git history, tags или выполнять
+  auto-push.
+
+## Подключение к Gitea
+
+HTTPS clone:
+
+```bash
+git clone https://git.iri1968.dpdns.org/awatch-rus/AWatch-rus.git
+```
+
+SSH clone может быть добавлен отдельным шагом после настройки ключей Gitea.
+SSH private key не хранить в репозитории.
+
+## Первичная проверка репозитория
+
+```bash
+cd AWatch-rus
+git remote -v
+bash scripts/registry_readiness_check.sh
+```
+
+GitHub используется как public mirror only и не является primary registry
+source/build/release contour.
@@ -1,8 +1,8 @@
 # AWatch-rus: readiness для реестра российского ПО

 Статус: подготовительный документ. Документ фиксирует текущее состояние
-registry-readiness пакета и не является юридическим заключением о готовности
-подачи или принятия AWatch-rus в реестр российского ПО.
+registry-readiness пакета, не подтверждает готовность подачи и не подтверждает
+юридический результат рассмотрения AWatch-rus для реестра российского ПО.

 ## Назначение

@@ -58,6 +58,16 @@ Done / partially done:
 - Offsite backup в РФ.
 - Финальная юридическая проверка registry package.

+## Новый статус registry-readiness
+
+- Russian Git contour: partially done / done.
+- Gitea backup: partially done.
+- Russian build-runner: planned.
+- Release artifacts storage in RF: planned.
+- Release evidence automation: partially done after this task.
+- Restore test: required.
+- Legal rightsholder confirmation: required.
+
 ## Ограничения формулировок

 AWatch-rus не заявляется как сертифицированное средство защиты информации,
@@ -1,5 +1,40 @@
 # Registry readiness changelog

+## 2026-06-21
+
+Added:
+
+- Russian build-runner readiness docs.
+- Build-runner setup runbook.
+- Release evidence runbook.
+- Release artifacts storage policy.
+- `scripts/build_release_evidence.sh`.
+- `scripts/check_release_evidence.sh`.
+
+Changed:
+
+- Updated registry evidence manifest with build-runner plan.
+- Updated registry readiness checks for build-runner and release evidence
+  requirements.
+
+Runtime impact:
+
+- No runtime/product code changes.
+- No API changes.
+- No UI changes.
+- Rust/runtime checks not required: registry documentation and release evidence
+  script update only.
+
+Remaining gaps:
+
+- Actual `awatch-build-01` server provisioning.
+- Build-runner first successful release candidate build.
+- SBOM tool installation decision.
+- Release artifacts storage in RF.
+- Restore test for Gitea backup.
+- Legal rightsholder confirmation.
+- Final legal review.
+
 ## 2026-06-20 / 2026-06-21

 Added:
@@ -0,0 +1,46 @@
+# Release artifacts storage
+
+Статус: planned / partially implemented. Required before registry submission:
+yes.
+
+## Целевая модель
+
+Release artifacts должны храниться в российском контуре. GitHub Releases не
+должны быть primary release storage для registry-readiness. Если GitHub
+Releases используются, они могут быть только public mirror.
+
+Возможные варианты:
+
+- отдельный каталог на `awatch-build-01`;
+- отдельный REG.RU VPS;
+- российское S3-compatible хранилище;
+- `releases.iri1968.dpdns.org` или `releases.awatch-rus.ru` в будущем.
+
+## Обязательные файлы
+
+- Source archive.
+- Binary archive.
+- `SHA256SUMS`.
+- SBOM CycloneDX.
+- SBOM SPDX.
+- `cargo-metadata.json`.
+- `cargo-tree.txt`.
+- Smoke logs.
+- Release evidence manifest.
+- Release notes.
+- Version output.
+- Health/readiness output, если применимо.
+
+## Evidence требования
+
+Для каждого release candidate фиксировать:
+
+- storage location;
+- timestamp;
+- release version;
+- commit SHA или tag;
+- checksum verification result;
+- responsible person placeholder: `[ЗАПОЛНИТЬ ПРАВООБЛАДАТЕЛЕМ]`.
+
+До выбора и проверки хранилища нельзя утверждать, что release artifact storage
+полностью готов для подачи в реестр.
@@ -44,3 +44,27 @@
 build-runner и storage release artifacts в РФ или документировать принятую
 владельцем схему. До этого нельзя утверждать, что source/build/release contour
 полностью закрыт для подачи.
+
+## Build-runner evidence
+
+Для `awatch-build-01` фиксировать:
+
+- hostname;
+- provider;
+- OS;
+- `rustc` / `cargo` versions;
+- git commit;
+- tag/version;
+- checks;
+- artifacts;
+- SBOM;
+- SHA256;
+- smoke logs;
+- skipped checks with reasons;
+- `generated_at`;
+- operator/responsible person placeholder:
+  `[ЗАПОЛНИТЬ ПРАВООБЛАДАТЕЛЕМ]`.
+
+Evidence должен формироваться скриптом `scripts/build_release_evidence.sh` и
+проверяться через `scripts/check_release_evidence.sh`. До первого успешного
+release candidate build нельзя утверждать, что release evidence production-ready.
@@ -0,0 +1,71 @@
+# Release evidence runbook
+
+Статус: registry-readiness runbook. Документ описывает выпуск release
+candidate на российском build-runner `awatch-build-01`. Он не утверждает, что
+release evidence уже production-ready до первого успешного запуска.
+
+## Процесс release candidate
+
+1. Checkout конкретного commit SHA или tag.
+2. Clean build environment.
+3. Выполнить `cargo fmt --all --check`.
+4. Выполнить `cargo test --workspace`.
+5. Выполнить `cargo clippy --workspace --all-targets -- -D warnings`.
+6. Выполнить `cargo build --workspace --release`.
+7. Выполнить `bash scripts/registry_readiness_check.sh`.
+8. Выполнить release evidence check:
+   `bash scripts/check_release_evidence.sh <evidence-dir>`.
+9. Запустить доступные smoke-тесты:
+   `node scripts/deployment-readiness-smoke.mjs`,
+   `node scripts/pilot-validation-smoke.mjs`,
+   `node scripts/browser-conformance-smoke.mjs`, если не требует live stand,
+   `bash scripts/validate_install_kit.sh`, если применимо.
+10. Сформировать source archive.
+11. Сформировать binary artifacts archive.
+12. Сформировать `SHA256SUMS`.
+13. Сформировать `cargo-metadata.json`.
+14. Сформировать `cargo-tree.txt`.
+15. Сформировать SBOM CycloneDX/SPDX, если tools доступны.
+16. Сформировать release evidence manifest.
+17. Сохранить logs.
+18. Сохранить final report.
+
+Если smoke требует live stand, не удалять и не скрывать его. В release report
+фиксировать: `skipped: requires live stand`.
+
+## Автоматизация
+
+Основной скрипт:
+
+```bash
+RELEASE_VERSION=registry-candidate-YYYYMMDD-HHMMSS \
+RELEASE_COMMIT=<commit-sha-or-tag> \
+OUTPUT_DIR=release-evidence/<release-version> \
+bash scripts/build_release_evidence.sh
+```
+
+Для documentation-only изменения допустимо:
+
+```bash
+DOCS_ONLY=1 bash scripts/build_release_evidence.sh
+```
+
+`DOCS_ONLY=1` должен явно попасть в report. Это не должно использоваться для
+product/runtime release candidate.
+
+## Обязательные результаты
+
+- `release-evidence-manifest.json`.
+- `RELEASE_EVIDENCE_REPORT_RU.md`.
+- `SHA256SUMS`.
+- `logs/`.
+- Source archive.
+- Binary artifacts archive или documented skip только для `DOCS_ONLY=1`.
+- `cargo-metadata.json` или documented skip.
+- `cargo-tree.txt` или documented skip.
+
+## Conservative claims
+
+Release evidence не является подтверждением юридически завершенной регистрации
+в реестре РФ. Перед официальной подачей требуются rightsholder confirmation,
+финальная юридическая проверка и проверка фактического build-runner.
@@ -0,0 +1,101 @@
+# Russian build-runner readiness
+
+Статус: registry-readiness plan. Документ описывает целевую архитектуру
+российского build-runner для AWatch-rus и не утверждает, что build-runner уже
+развернут или что release evidence уже production-ready.
+
+## Назначение
+
+Build-runner нужен для воспроизводимой сборки release candidate, выполнения
+проверок, подготовки artifacts и формирования release evidence в российском
+контуре. Он должен быть отделен от Gitea-сервера, чтобы тяжелые Rust workspace
+build/test/check задачи не конкурировали с Git-хранилищем, HTTPS reverse proxy
+и backup-процедурами.
+
+## Целевая роль
+
+| Параметр | Значение |
+| --- | --- |
+| Recommended hostname | `awatch-build-01` |
+| Recommended provider | REG.RU VPS / cloud server или другой российский сервер |
+| Target location | Russian Federation |
+| Role | российский контур сборки и выпуска release artifacts |
+| Source repository | `https://git.iri1968.dpdns.org/awatch-rus/AWatch-rus` |
+| GitHub role | public mirror only |
+
+## Почему не awatch-git-01
+
+`awatch-git-01` должен оставаться Git-сервером: self-hosted Gitea,
+repository, `docs/registry/`, HTTPS/Nginx и Gitea backup. Тяжелые сборки,
+`cargo test --workspace`, `cargo clippy`, SBOM generation и packaging могут
+создавать высокую нагрузку на CPU, RAM и диск. Поэтому registry-readiness
+architecture разделяет:
+
+- `awatch-git-01`: source repository and documentation contour;
+- `awatch-build-01`: build/test/check/release evidence contour.
+
+## Минимальная конфигурация
+
+- 4 vCPU.
+- 8 GB RAM.
+- 100+ GB SSD/NVMe.
+- Debian 12 или Ubuntu 24.04 LTS.
+
+## Экономная конфигурация только для docs/check
+
+- 2 vCPU.
+- 4 GB RAM.
+- 80 GB SSD.
+
+Экономная конфигурация допустима только для documentation checks,
+registry-readiness checks и легких smoke. Ее нельзя считать достаточной для
+полного Rust workspace release build без отдельной проверки.
+
+## Рекомендуемая конфигурация для Rust workspace
+
+- 4 vCPU.
+- 8-16 GB RAM.
+- 120+ GB SSD/NVMe.
+- Debian 12 или Ubuntu 24.04 LTS.
+
+## Release artifacts storage
+
+Release artifacts должны храниться в российском контуре. Целевые варианты
+описаны в `docs/registry/RELEASE_ARTIFACTS_STORAGE_RU.md`. GitHub Releases
+могут быть public mirror, но не primary release storage для registry-readiness.
+
+## Evidence files
+
+Build-runner должен формировать:
+
+- source archive;
+- binary artifacts archive;
+- `SHA256SUMS`;
+- `cargo-metadata.json`;
+- `cargo-tree.txt`;
+- SBOM CycloneDX, если инструмент доступен;
+- SBOM SPDX, если инструмент доступен;
+- logs for fmt/test/clippy/build/registry/smoke checks;
+- release evidence manifest;
+- release evidence report;
+- version output, если применимо;
+- health/readiness output, если применимо.
+
+## Требует подтверждения правообладателем
+
+- Фактический provider и location build-runner.
+- Ответственный за build-runner.
+- Политика доступа.
+- Release artifacts storage в РФ.
+- Offsite backup policy для release artifacts.
+- Достаточность evidence для официального пакета документов.
+
+## Текущий статус
+
+- Russian Git contour: partially done / done.
+- Gitea backup: partially done.
+- Russian build-runner: planned.
+- Release artifacts storage in RF: planned.
+- Release evidence automation: partially done after this task.
+- Restore test: required.
+- Legal rightsholder confirmation: required.
@@ -38,6 +38,41 @@
    "restore_tested": false,
    "production_ready": false
  },
+  "build_runner": {
+    "status": "planned",
+    "target_hostname": "awatch-build-01",
+    "target_provider": "REG.RU VPS / cloud server or another Russian-hosted server",
+    "target_location": "Russian Federation",
+    "separate_from_git_server": true,
+    "recommended_specs": {
+      "cpu": "4 vCPU",
+      "ram": "8-16 GB",
+      "disk": "120+ GB SSD/NVMe",
+      "os": [
+        "Debian 12",
+        "Ubuntu 24.04 LTS"
+      ]
+    },
+    "required_checks": [
+      "cargo fmt --all --check",
+      "cargo test --workspace",
+      "cargo clippy --workspace --all-targets -- -D warnings",
+      "cargo build --workspace --release",
+      "registry_readiness_check",
+      "release_evidence_check"
+    ],
+    "release_evidence": {
+      "source_archive": true,
+      "binary_archive": true,
+      "sha256sums": true,
+      "cargo_metadata": true,
+      "cargo_tree": true,
+      "sbom_cyclonedx": "if_tool_available",
+      "sbom_spdx": "if_tool_available",
+      "smoke_logs": true,
+      "release_manifest": true
+    }
+  },
  "github_role_note": "GitHub is a public mirror only, not the target primary source/build/release contour for registry-readiness.",
  "remaining_gaps": [
    "legal rightsholder confirmation",
@@ -49,11 +84,11 @@
    "final registry legal review"
  ],
  "forbidden_claims_not_made": [
-    "FSTEC/FSB certification",
-    "SIEM replacement",
-    "DLP replacement",
-    "ML/LLM-based detection",
-    "cloud dependency",
-    "automatic remediation"
+    "not_claimed: FSTEC/FSB certification",
+    "not_claimed: SIEM replacement",
+    "not_claimed: DLP replacement",
+    "not_claimed: ML/LLM-based detection",
+    "not_claimed: cloud dependency",
+    "not_claimed: automatic remediation"
  ]
 }