docs(registry): document Russian Gitea contour and registry docs policy

2026-06-21 05:56:11 +03:00
parent 4ba055fcdf
commit 6861df9be4
10 changed files with 189 additions and 27 deletions
@@ -218,11 +218,15 @@ collectors.
  [commercial positioning](docs/REGISTRY_COMMERCIAL_POSITIONING_RU.md),
  [readiness checklist](docs/REGISTRY_READINESS_CHECKLIST_RU.md).

- Registry-readiness infrastructure:
-  Russian Git contour:
-  `https://git.iri1968.dpdns.org/awatch-rus/AWatch-rus`;
-  GitHub role: public mirror;
-  detailed docs: [docs/registry/](docs/registry/REGISTER_RU_SOFTWARE_READINESS_RU.md).
+### Подготовка к реестру российского ПО
+
+- Основной российский Git-контур:
+  `https://git.iri1968.dpdns.org/awatch-rus/AWatch-rus`.
+- GitHub используется как публичное зеркало.
+- Доказательная документация:
+  [docs/registry/](docs/registry/REGISTER_RU_SOFTWARE_READINESS_RU.md).
+- Gitea Wiki используется только как навигация, не как единственный источник
+  документов.

 - [Позиционирование для реестра российского ПО](docs/RUSSIAN_SOFTWARE_REGISTRY_POSITIONING_RU.md)
 - [Сведения для подачи в реестр](REGISTER_RU_SOFTWARE.md)
@@ -16,6 +16,7 @@
 | Backup format | Gitea dump ZIP |
 | Checksum | SHA256 |
 | Retention | 14 days |
+| Restore tested | `false` until a separate test restore is completed |

 Целевой backup script использует `gitea dump`, создает ZIP backup и отдельный
 SHA256 checksum. Каталог `/var/backups/gitea` должен быть доступен только
@@ -46,16 +47,26 @@ Restore является ручной процедурой и требует т
 Общий порядок:

 1. Подготовить отдельный сервер или isolated test instance.
-2. Установить совместимую версию Gitea.
+2. Установить ту же версию Gitea, из которой был создан dump.
 3. Остановить Gitea на целевом тестовом сервере.
 4. Проверить SHA256 checksum выбранного ZIP backup.
-5. Выполнить восстановление из `gitea dump` согласно официальной процедуре
-   Gitea для используемой версии.
-6. Проверить права на каталоги, repository storage, database, custom config и
-   attachments.
-7. Запустить Gitea.
-8. Выполнить post-restore checks.
-9. Зафиксировать timestamp, backup filename, checksum, Gitea version,
+5. Распаковать dump.
+6. Восстановить `app.ini`, data, repositories и database согласно официальной
+   restore-процедуре Gitea для используемой версии.
+7. Исправить ownership и permissions:
+
+```bash
+chown -R git:git /var/lib/gitea
+chown root:git /etc/gitea/app.ini
+chmod 640 /etc/gitea/app.ini
+```
+
+8. Запустить Gitea.
+9. Выполнить `gitea doctor check`.
+10. Если менялся путь установки или переносился сервер, выполнить
+    `gitea admin regenerate hooks`.
+11. Выполнить post-restore checks.
+12. Зафиксировать timestamp, backup filename, checksum, Gitea version,
   restore duration и результат проверки.

 ## Post-restore checks
@@ -66,6 +77,12 @@ curl -L https://git.iri1968.dpdns.org | head
 gitea doctor check
 ```

+Также открыть в браузере:
+
+```text
+https://git.iri1968.dpdns.org/awatch-rus/AWatch-rus
+```
+
 Если менялся путь установки или сервер переносился, выполнить:

 ```bash
@@ -75,6 +92,8 @@ gitea admin regenerate hooks
 ## Ограничения

 - Restore-runbook не заменяет фактический restore test.
+- `restore_tested=false`, пока не выполнено тестовое восстановление на
+  отдельном сервере.
 - Backup не должен считаться production-ready, пока restore не проверен на
  отдельном сервере.
 - Offsite copy должна быть описана отдельно до финальной подачи в реестр.
@@ -6,21 +6,14 @@ GitHub mirror.

 ## Целевая схема remotes

-Primary Russian Git contour:
+Primary registry-readiness remote:

 ```text
 ru-origin:
 https://git.iri1968.dpdns.org/awatch-rus/AWatch-rus.git
 ```

-Public mirror / external public repository:
-
-```text
-github:
-git@github.com:igor04091968/AWatch-rus.git
-```
-
-или:
+GitHub public mirror:

 ```text
 github:
@@ -57,14 +50,30 @@ git push ru-origin main
 git push ru-origin --tags
 ```

+Добавить GitHub mirror remote, если он еще не настроен:
+
+```bash
+git remote add github https://github.com/igor04091968/AWatch-rus.git
+```
+
+Обновить GitHub mirror:
+
+```bash
+git push github main
+git push github --tags
+```
+
 ## Операционные предупреждения

+- Реальные remote names сначала проверить через `git remote -v`.
 - При работе через HTTPS использовать Gitea token/password согласно настройкам
  Gitea.
 - SSH-ключи для Gitea настраиваются отдельно и не должны храниться в
  репозитории.
 - GitHub остается публичным зеркалом и внешней площадкой; он не является
  primary registry source/build system в registry-readiness документации.
+- При конфликте истории использовать `pull`/`rebase` только после ручной
+  проверки расхождений.
 - Перед release evidence фиксировать `git remote -v`, commit hash, tag,
  timestamp и источник сборки.
 - Любые секреты, токены, приватные ключи и персональные данные не включать в
@@ -13,10 +13,30 @@ registry-readiness пакета и не является юридическим
 Новые сведения по российскому Git-контуру требуют финального подтверждения
 правообладателем и внесения в официальный пакет документов перед подачей.

+## Текущее состояние инфраструктуры
+
+- Российский Git-контур развернут как целевой контур для registry-readiness.
+- Self-hosted Gitea развернута на REG.RU VPS / cloud server.
+- Основной целевой URL:
+  `https://git.iri1968.dpdns.org/awatch-rus/AWatch-rus`.
+- GitHub используется как публичное зеркало.
+- Встроенная Gitea Wiki может использоваться только как навигационная
+  страница.
+- Доказательная документация должна храниться в `docs/registry/`.
+- Backup-контур начат, но `restore_tested=false` до проверки восстановления
+  на отдельном сервере.
+
 ## Текущее состояние

 Done / partially done:

+- REG.RU VPS создан.
+- Gitea установлена.
+- HTTPS включен.
+- Организация `awatch-rus` создана.
+- Репозиторий AWatch-rus мигрирован.
+- `docs/registry/` используется как основной документальный пакет.
+- Backup через `gitea dump` начат.
 - Развернут целевой российский Git-контур для registry-readiness.
 - Развернута self-hosted Gitea на REG.RU VPS / cloud server.
 - Репозиторий AWatch-rus мигрирован в Gitea:
@@ -35,7 +55,7 @@ Done / partially done:
  выбранной схемы хранения.
 - Протестированная restore-процедура Gitea на отдельном сервере.
 - Документированная access control policy для Gitea.
- Документированная offsite copy для backup-архивов.
+- Offsite backup в РФ.
 - Финальная юридическая проверка registry package.

 ## Ограничения формулировок
@@ -5,9 +5,13 @@
 Added:

 - REG.RU/Gitea Russian Git contour documentation.
+- Documented repository migration to
+  `https://git.iri1968.dpdns.org/awatch-rus/AWatch-rus`.
 - Self-hosted Gitea repository reference:
  `https://git.iri1968.dpdns.org/awatch-rus/AWatch-rus`.
 - GitHub role as public mirror only.
+- Gitea Wiki policy as navigation-only, with `docs/registry/` as the
+  authoritative registry-readiness documentation package.
 - Gitea backup/restore runbook.
 - Registry evidence manifest updates for Gitea, backup ZIP, SHA256 checksum,
  systemd timer and restore status.
@@ -30,6 +34,7 @@ Remaining gaps:
 - Russian build-runner.
 - Release artifacts storage in RF.
 - Tested restore procedure.
+- Offsite backup in RF.
 - Documented access control policy.
 - Documented backup offsite copy.
 - Final registry legal review.
@@ -8,6 +8,8 @@

 Для российского Git-контура и backup-контура фиксировать:

+- Primary Git URL:
+  `https://git.iri1968.dpdns.org/awatch-rus/AWatch-rus`.
 - Gitea URL: `https://git.iri1968.dpdns.org/awatch-rus/AWatch-rus`.
 - Provider: REG.RU VPS / cloud server.
 - Platform: self-hosted Gitea.
@@ -20,7 +22,7 @@
 - SHA256 checksum evidence для backup ZIP.
 - Restore-runbook reference:
  `docs/registry/GITEA_BACKUP_AND_RESTORE_RUNBOOK_RU.md`.
- Timestamped evidence file, если он будет предоставлен владельцем.
+- Timestamped evidence file can be provided by rightsholder.

 ## Source evidence

@@ -4,7 +4,7 @@
 инфраструктуру хранения исходного кода и связанные ограничения. Он не
 фиксирует юридическую завершенность подачи в реестр российского ПО.

-## Текущий российский Git-контур
+## Российский Git-контур

 | Параметр | Значение |
 | --- | --- |
@@ -25,6 +25,13 @@ registry source/build/release contour для registry-readiness. Он может
 использоваться как публичное зеркало и внешняя площадка, но целевой российский
 контур хранения исходного кода для подготовки к реестру зафиксирован в Gitea.

+## Gap
+
+- Build-runner в РФ еще требуется.
+- Release artifacts storage в РФ еще требуется.
+- Backup restore test еще требуется.
+- Legal ownership evidence еще требуется.
+
 ## Сборочный контур

 Текущий документ фиксирует Git-контур хранения исходного кода. Российский
@@ -0,0 +1,50 @@
+# Wiki and documentation policy
+
+Статус: registry-readiness document. Документ фиксирует, какие источники
+документации считаются доказательными для подготовки к реестру российского ПО.
+
+## Политика документации
+
+- GitHub Wiki repository
+  `https://github.com/igor04091968/AWatch-rus.wiki.git` не обнаружен /
+  не используется как обязательный источник.
+- Gitea встроенная Wiki может использоваться как навигационная стартовая
+  страница.
+- Основной доказательный документальный пакет хранится в `docs/registry/`.
+- `README.md` должен ссылаться на `docs/registry/`.
+- Wiki не должна содержать единственные экземпляры критичных документов.
+- При необходимости первая страница Wiki должна ссылаться на `README.md` и
+  `docs/registry/`.
+
+## Рекомендуемый текст для Gitea Wiki Home
+
+```markdown
+# AWatch-rus
+
+Основная документация проекта находится в репозитории:
+
+* README.md
+* docs/
+* docs/registry/
+
+## Реестр российского ПО
+
+Материалы подготовки к реестру российского ПО находятся в:
+
+* docs/registry/REGISTER_RU_SOFTWARE_READINESS_RU.md
+* docs/registry/SOURCE_CODE_AND_BUILD_INFRASTRUCTURE_RU.md
+* docs/registry/GIT_RU_MIRRORING_RUNBOOK_RU.md
+* docs/registry/GITEA_BACKUP_AND_RESTORE_RUNBOOK_RU.md
+
+## Основной российский Git-контур
+
+https://git.iri1968.dpdns.org/awatch-rus/AWatch-rus
+
+GitHub используется как публичное зеркало.
+```
+
+## Ограничения
+
+Wiki не является единственным источником доказательных документов и не заменяет
+tracked files в репозитории. Для registry-readiness ссылаться на committed
+документы из `docs/registry/`.
@@ -4,9 +4,15 @@
  "status": "registry-readiness infrastructure evidence manifest",
  "updated_at": "2026-06-21",
  "primary_source_repository": "https://git.iri1968.dpdns.org/awatch-rus/AWatch-rus",
+  "primary_git_clone_url_https": "https://git.iri1968.dpdns.org/awatch-rus/AWatch-rus.git",
  "primary_git_platform": "self-hosted Gitea",
  "primary_git_provider": "REG.RU VPS / cloud server",
  "github_role": "public_mirror_only",
+  "wiki_policy": {
+    "github_wiki_detected": false,
+    "gitea_builtin_wiki": "navigation_only",
+    "authoritative_docs_path": "docs/registry"
+  },
  "infrastructure": {
    "git_url": "https://git.iri1968.dpdns.org",
    "organization": "awatch-rus",
@@ -27,11 +27,16 @@ require_grep() {
  fi
 }

+if [[ ! -d "$REGISTRY_DIR" ]]; then
+  fail "missing_directory:docs/registry"
+fi
+
 required_files=(
  "docs/registry/REGISTER_RU_SOFTWARE_READINESS_RU.md"
  "docs/registry/SOURCE_CODE_AND_BUILD_INFRASTRUCTURE_RU.md"
  "docs/registry/GIT_RU_MIRRORING_RUNBOOK_RU.md"
  "docs/registry/GITEA_BACKUP_AND_RESTORE_RUNBOOK_RU.md"
+  "docs/registry/WIKI_AND_DOCUMENTATION_POLICY_RU.md"
  "docs/registry/RELEASE_EVIDENCE_MANIFEST_RU.md"
  "docs/registry/INSTALLATION_AND_TEST_INSTANCE_RU.md"
  "docs/registry/LIFECYCLE_AND_SUPPORT_RU.md"
@@ -45,7 +50,26 @@ for file in "${required_files[@]}"; do
 done

 if [[ -s "$MANIFEST" ]]; then
-  if command -v python3 >/dev/null 2>&1; then
+  if command -v jq >/dev/null 2>&1; then
+    jq -e . "$MANIFEST" >/dev/null || fail "invalid_json:docs/registry/registry-evidence-manifest.json"
+    jq -e '
+      .primary_source_repository == "https://git.iri1968.dpdns.org/awatch-rus/AWatch-rus"
+      and .primary_git_clone_url_https == "https://git.iri1968.dpdns.org/awatch-rus/AWatch-rus.git"
+      and .primary_git_platform == "self-hosted Gitea"
+      and .primary_git_provider == "REG.RU VPS / cloud server"
+      and .github_role == "public_mirror_only"
+      and .wiki_policy.github_wiki_detected == false
+      and .wiki_policy.gitea_builtin_wiki == "navigation_only"
+      and .wiki_policy.authoritative_docs_path == "docs/registry"
+      and .backup.enabled == true
+      and .backup.tool == "gitea dump"
+      and .backup.path == "/var/backups/gitea"
+      and .backup.checksum == "sha256"
+      and .backup.retention_days == 14
+      and .backup.systemd_timer == "awatch-gitea-backup.timer"
+      and .backup.restore_tested == false
+    ' "$MANIFEST" >/dev/null || fail "manifest_required_fields"
+  elif command -v python3 >/dev/null 2>&1; then
    python3 -m json.tool "$MANIFEST" >/dev/null || fail "invalid_json:docs/registry/registry-evidence-manifest.json"
    python3 - "$MANIFEST" <<'PY' || fail "manifest_required_fields"
 import json
@@ -57,6 +81,7 @@ with open(path, "r", encoding="utf-8") as fh:

 expected = {
    "primary_source_repository": "https://git.iri1968.dpdns.org/awatch-rus/AWatch-rus",
+    "primary_git_clone_url_https": "https://git.iri1968.dpdns.org/awatch-rus/AWatch-rus.git",
    "primary_git_platform": "self-hosted Gitea",
    "primary_git_provider": "REG.RU VPS / cloud server",
    "github_role": "public_mirror_only",
@@ -65,6 +90,16 @@ for key, value in expected.items():
    if data.get(key) != value:
        raise SystemExit(f"{key} mismatch")

+wiki_policy = data.get("wiki_policy") or {}
+wiki_expected = {
+    "github_wiki_detected": False,
+    "gitea_builtin_wiki": "navigation_only",
+    "authoritative_docs_path": "docs/registry",
+}
+for key, value in wiki_expected.items():
+    if wiki_policy.get(key) != value:
+        raise SystemExit(f"wiki_policy.{key} mismatch")
+
 backup = data.get("backup") or {}
 backup_expected = {
    "enabled": True,
@@ -89,13 +124,18 @@ fi

 require_grep "git\\.iri1968\\.dpdns\\.org" "docs/registry/SOURCE_CODE_AND_BUILD_INFRASTRUCTURE_RU.md" "gitea_domain_source_infra"
 require_grep "git\\.iri1968\\.dpdns\\.org" "docs/registry/GIT_RU_MIRRORING_RUNBOOK_RU.md" "gitea_domain_git_runbook"
+require_grep "git\\.iri1968\\.dpdns\\.org" "docs/registry/WIKI_AND_DOCUMENTATION_POLICY_RU.md" "gitea_domain_wiki_policy"
 require_grep "git\\.iri1968\\.dpdns\\.org" "README.md" "gitea_domain_readme"
 require_grep "GitHub[[:space:]]*=[[:space:]]*public mirror only|public mirror only" "docs/registry/SOURCE_CODE_AND_BUILD_INFRASTRUCTURE_RU.md" "github_public_mirror_source_infra"
 require_grep "GitHub[[:space:]]*=[[:space:]]*public mirror only|public mirror only" "docs/registry/GIT_RU_MIRRORING_RUNBOOK_RU.md" "github_public_mirror_git_runbook"
-require_grep "public mirror" "README.md" "github_public_mirror_readme"
+require_grep "GitHub.*публичн|public mirror" "docs/registry/WIKI_AND_DOCUMENTATION_POLICY_RU.md" "github_public_mirror_wiki_policy"
+require_grep "public mirror|публичн.*зеркал" "README.md" "github_public_mirror_readme"
 require_grep "GITEA_BACKUP_AND_RESTORE_RUNBOOK_RU\\.md|Restore outline|Post-restore checks" "docs/registry/GITEA_BACKUP_AND_RESTORE_RUNBOOK_RU.md" "backup_restore_runbook"
 require_grep "awatch-gitea-backup\\.timer" "docs/registry/GITEA_BACKUP_AND_RESTORE_RUNBOOK_RU.md" "backup_timer"
 require_grep "sha256|SHA256" "docs/registry/GITEA_BACKUP_AND_RESTORE_RUNBOOK_RU.md" "backup_sha256"
+require_grep "restore_tested=false|restore_tested..false|\"restore_tested\"[[:space:]]*:[[:space:]]*false" "docs/registry/GITEA_BACKUP_AND_RESTORE_RUNBOOK_RU.md" "restore_tested_false_runbook"
+require_grep "\"restore_tested\"[[:space:]]*:[[:space:]]*false" "docs/registry/registry-evidence-manifest.json" "restore_tested_false_manifest"
+require_grep "docs/registry" "docs/registry/WIKI_AND_DOCUMENTATION_POLICY_RU.md" "authoritative_docs_path_wiki_policy"

 scan_files=(
  "$ROOT/README.md"