From 9e02b696ba35294be41a1545f570bb285d803a9f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CNaeel=E2=80=9D?= Date: Thu, 3 Sep 2026 08:06:59 +0300 Subject: [PATCH] fix(docs-pipeline): default DOCS_GEN_DIR -> generated//docs; document env setup + S3 via VM --- DOCS_PIPELINE/README.md | 39 ++++++++++++++++++++++ TOOLS/scripts/04_build_and_publish_docs.sh | 4 +-- 2 files changed, 41 insertions(+), 2 deletions(-) diff --git a/DOCS_PIPELINE/README.md b/DOCS_PIPELINE/README.md index 606fc06..d2fe9d1 100644 --- a/DOCS_PIPELINE/README.md +++ b/DOCS_PIPELINE/README.md @@ -106,6 +106,45 @@ API стенда ──▶ generated/<стенд>/resources_yaml/ ──▶ gene - Доставка до браузера: S3 → ВМ-зеркало (`/var/www/tf-docs/`) → nginx ВМ отдаёт `//` → под `tf_docs` (reverse-proxy в кластере) → `https://tf-docs.nodejsk8s.dev.nubes.ru//`. - ВМ отдаёт также по прямому IP `http://5.172.178.213//`. +## Требования к окружению (настроено 2026-09-03) + +Чтобы пайплайн работал **штатно и не ломался**, на машине сборки должно быть: + +| Компонент | Как проверить | Что ставить | +|---|---|---| +| `python3-venv` (Debian/Ubuntu) | `python3 -m venv /tmp/v && ls /tmp/v/bin/pip` | `sudo apt install -y python3.12-venv` — без него venv создаётся БЕЗ pip | +| `.venv` проекта с mkdocs | `.venv/bin/python -m mkdocs --version` | пересоздать: `rm -rf .venv && python3 -m venv .venv && .venv/bin/pip install mkdocs==1.6.1 mkdocs-material==9.7.3` | +| Системный mkdocs (запасной) | `python3 -m mkdocs --version` | `pip3 install --user mkdocs==1.6.1 mkdocs-material==9.7.3` | +| `mc` (MinIO client) | `mc --version` | см. docs min.io | +| docker + образ `squidfunk/mkdocs-material` (запасной) | `docker images` | `docker pull squidfunk/mkdocs-material` | + +> **Почему так.** `04` при `--profile` собирает через `.venv` проекта. Если `.venv` пустой/сломан (нет pip/mkdocs) — сборка падает. Корень: без системного пакета `python3.12-venv` виртуальное окружение создаётся без `pip`/`ensurepip`. Это чинится один раз (apt + пересоздание `.venv`), дальше не ломается. +> Версии зафиксированы: `mkdocs==1.6.1`, `mkdocs-material==9.7.3` (совпадают и в системном python3, и в `.venv`). + +## Публикация: где запускать `mc mirror` + +S3 (`s3.msk-1.ngcloud.ru`) из локальной сети **рвёт большие ответы** (рекурсивный листинг >нескольких сотен объектов зависает: `mc: Unable to list ... unexpected EOF`; малые `mc ls`/`mc cp` работают). Поэтому **заливку на S3 делать с ВМ `5.172.178.213`** — у неё быстрый канал до S3 (~10 МБ/с). + +Полный цикл публикации стенда (сборка локально → S3 с ВМ → зеркало на ВМ): + +```bash +# 1. Сборка (локально, штатно) +./TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/test 5.0.8 +# (если site/ собирался docker-ом от root — mkdocs не сможет его перезаписать: +# sudo rm -rf site или docker run --rm -v $PWD:/docs --entrypoint rm squidfunk/mkdocs-material -rf /docs/site) + +# 2. Передать собранный site/ на ВМ +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 -' + +# 3. Залить на S3 с ВМ (быстрый канал) +ssh naeel@5.172.178.213 'mc mirror --overwrite --remove ~/tmp-docs-site/ registry/terraform-registry/docs/nubes-test/nubes/' + +# 4. Обновить зеркало /var/www/tf-docs (откуда nginx отдаёт сайт) +ssh naeel@5.172.178.213 'mc mirror --overwrite --remove "registry/terraform-registry/docs/nubes-test/nubes/" /var/www/tf-docs/nubes-test/' +``` + +> ⚠️ Если `mc mirror`/`mc ls -r` локально зависает — это не баг скрипта, а сеть до S3; заливать с ВМ. + ## Быстрые команды ```bash diff --git a/TOOLS/scripts/04_build_and_publish_docs.sh b/TOOLS/scripts/04_build_and_publish_docs.sh index 213c751..50842b4 100755 --- a/TOOLS/scripts/04_build_and_publish_docs.sh +++ b/TOOLS/scripts/04_build_and_publish_docs.sh @@ -74,8 +74,8 @@ S3CFG_REGISTRY="$(resolve_root_path "$S3CFG_REGISTRY")" TMP_DOCS_DIR="" if [[ -n "$PROFILE_DIR" ]]; then - # ⛔ NEVER merge with docs/ — ONLY generated docs from docs_gen// - DOCS_GEN_DIR="${DOCS_GEN_DIR:-generated/test}" + # ⛔ NEVER merge with docs/ — ONLY generated docs from generated//docs/ + DOCS_GEN_DIR="${DOCS_GEN_DIR:-generated/$(basename "$PROFILE_DIR")/docs}" DOCS_GEN_DIR="$(resolve_root_path "$DOCS_GEN_DIR")" if [[ -d "$DOCS_GEN_DIR" ]]; then export MKDOCS_DOCS_DIR="$DOCS_GEN_DIR"