# Пересобрать и опубликовать документацию стендов (на сайтах старые версии провайдера)

Дата: 2026-10-02 | Статус: не начато (отдельная работа, по отдельной команде)

## Суть проблемы

Опубликованные сайты документации отдают **устаревшую версию провайдера** в примерах
(`required_providers … version = …`).

| Стенд | На сайте | `VERSION` в `TOOLS/config/<стенд>/profile.env` | Итог |
|---|---|---|---|
| `nubes-test` → `https://tf-docs.nodejsk8s.dev.nubes.ru/nubes-test/` | **5.0.5** | 3.0.0 | устарел |
| `nubes-dev` → `https://tf-docs.nodejsk8s.dev.nubes.ru/nubes-dev/` | **2.0.23** | 2.0.0 | устарел |
| `nubes` (prod) → `https://tf-docs.nodejsk8s.dev.nubes.ru/nubes/` | 1.0.0 | 1.0.0 | совпадает |

Проверялось на странице `…/<стенд>/curated/postgres/pg_user_db/` (в исходнике там
плейсхолдер `{{VERSION}}`).

## Причина

В исходниках `docs/` версии нет — при сборке плейсхолдеры подставляются значениями из
профиля стенда (`TOOLS/scripts/04_build_and_publish_docs.sh:185-198`). Значит сайты
собраны **до** смены нумерации версий (2026-09-03) и с тех пор не пересобирались.

Дополнительные подтверждения старости публикации:

- на `nubes-test` нет страниц, которые уже есть на `nubes-dev`: `k8svalkey`,
  `k8s_ziti_controller`, `nodered`, `nifi`;
- на `nubes-test` нет правок страницы `curated/crud/three_apps.md` (коммит `ab9f7d2`);
- локальная сборка `site/` (2026-09-28 09:40) — сборка dev-стенда, строки `5.0.5` в ней
  нет, то есть на S3 лежит сборка **старше** этого `site/`.

## Что уже сделано вручную (2026-10-02, временно)

Страница `curated/crud/three_apps/` опубликована **только она**, отдельно от полной пересборки
(команда владельца: «эта ручная заливка — временная, для демонстрации коллегам»):

- собрано `04 --profile TOOLS/config/test` с заблокированной публикацией (сборка без заливки сайта);
- залито в S3 (`docs/nubes-test/nubes/curated/crud/three_apps/index.html`);
- скопировано на ВМ в `/var/www/tf-docs/nubes-test/curated/crud/three_apps/` (именно оттуда
  nginx отдаёт сайт — S3-объект сам по себе на живом сайте не появляется);
- проверено: `https://tf-docs.nodejsk8s.dev.nubes.ru/nubes-test/curated/crud/three_apps/` → 200,
  версия на странице 3.0.0.

Следствие: страница доступна **только по прямому адресу** — в меню остальных страниц стенда
ссылки на неё нет (их навигация от старой сборки). Полная пересборка ниже нужна именно для
этого: чтобы пример появился в разделе «Проверенные примеры» в меню, и чтобы версии во всех
примерах совпали с `profile.env`.

## Что сделать

1. Для каждого устаревшего стенда — сборка и публикация:

```bash
./TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/dev
./TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/test
```

2. Заливка на S3 делается **с ВМ `5.172.178.213`** (у локальной сети S3 рвёт большие
   ответы), полный порядок — в `DOCS_PIPELINE/README.md`, раздел «Публикация: где
   запускать `mc mirror`»:

```bash
tar -C site -cf - . | ssh naeel@5.172.178.213 'rm -rf ~/tmp-docs-site && mkdir -p ~/tmp-docs-site && tar -C ~/tmp-docs-site -xf -'
ssh naeel@5.172.178.213 'mc mirror --overwrite --remove ~/tmp-docs-site/ registry/terraform-registry/docs/<namespace>/nubes/'
ssh naeel@5.172.178.213 'mc mirror --overwrite --remove "registry/terraform-registry/docs/<namespace>/nubes/" /var/www/tf-docs/<namespace>/'
```

3. Проверить результат на живом сайте: на странице `…/<стенд>/curated/postgres/pg_user_db/`
   версия должна совпасть с `VERSION` из `profile.env` (`dev=2.0.0`, `test=3.0.0`,
   `prod=1.0.0`), и должны появиться страницы, которых на стенде не было.

## Заодно уедет (уже закоммичено в `docs/`)

- `curated/crud/three_apps.md` — страница переписана под схему `pg/` + `apps/`
  (коммит `ab9f7d2`) и дополнена разделом «Что пользователь задаёт сам» (коммит `39849bf`).
- страницы, добавленные с прошлой публикации (`k8svalkey`, `k8s_ziti_controller`,
  `nodered`, `nifi` — уже видны на dev, но не на test).

## Осторожно

- Публикация — это деплой: выполнять только по прямой команде владельца.
- `publish-docs.sh` публикует **без версии в URL** (`mc mirror --overwrite --remove`),
  старые файлы удаляются — после публикации проверить, что живые разделы на месте.
- Если `site/` собирался docker-ом от root, mkdocs не сможет перезаписать каталог:
  `sudo rm -rf site` или удалить через контейнер (см. `DOCS_PIPELINE/README.md`).

## Связанные документы

- `HISTORY/50_docs/2026-10-02_crud_docs_page_and_manual_pages_pipeline.md` — раздел 4:
  как это обнаружено (проверка страницы `nubes-test/curated/postgres/pg_user_db/`).
- `DOCS_PIPELINE/README.md` — актуальное описание сборки и публикации.
- `HISTORY/50_docs/2026-10-02_s3_static_website_docs_hosting.md` — хостинг документации
  из S3 (находки по static website на RGW).