meta(handoff): #1020 закрыта (деплой v0.5.1 + токен), прод-импорт, books yarn.lock — ложная тревога

.wiki/concepts/books-vds-no-gitea-actions.md

@@ -0,0 +1,29 @@
+---
+title: books-vds Gitea Actions выпилены — сборка только локально (решение vitya 2026-08-23)
+status: live
+tags: [books-vds, ci, gitea-actions, build, decision]
+---
+
+# Gitea Actions на books-vds — выпилены полностью (директива vitya 2026-08-23)
+
+**Решение юзера:** никакого Gitea Actions / CI-раннера. Сборка образов — **только локально на рабочей машине**, деплой — прямыми `PUT /api/stacks/<id>` в Portainer.
+
+## Что выпилено
+- Workflow-файлы удалены и запушены: `books/.gitea/workflows/{build,deploy,build-tools,build-sched-daemon}.yml`, `vds-ops-mcp/.gitea/workflows/build.yml` (там был РЕАЛЬНЫЙ автобилд `on: push` — «автосборка», которую юзер увидел).
+- books-vds (`89.253.255.133`): раннер вычищен под ноль:
+  - `systemctl stop/disable gitea-runner.service` + `rm /etc/systemd/system/gitea-runner.service`
+  - `rm -rf /opt/gitea-runner` (бинарник, config.yaml, .runner)
+  - `docker rm -f GITEA-ACTIONS-TASK-*` (job-контейнеры)
+  - `userdel -r gitea-runner`
+- vds-kzntsv: следов не было (проверено).
+
+## Процедура локальной сборки + публикации (проверена 2026-08-23)
+1. `git archive <sha> | tar -x -C /c/tmp/build` (чистый контекст, без node_modules/.git)
+2. `VERDACCIO_TOKEN=<jwt> docker build --secret id=verdaccio_token,env=VERDACCIO_TOKEN -f packages/<svc>/Dockerfile -t <svc>:<sha> .`
+3. `docker save` → tar (OCI layout: `index.json` + `blobs/sha256/*`)
+4. Заливка блобов curl'ом: HEAD-check → если нет — `POST /v2/<repo>/blobs/uploads/` → `PUT <Location>&digest=sha256:<d>` с телом (монолитный, Content-Length). Большой слой: `cat blob | curl -X PATCH -T -` (chunked) + финальный `PUT &digest` (Location брать из PATCH-ответа). Перед большим чтением файла — `sync; echo 3 > /proc/sys/vm/drop_caches` (books-vds 3.9GB RAM → OOM на 2GB файле).
+5. Манифест: если `index.json` → OCI index (multi-arch, у Docker Desktop так) — **класть дочерний amd64-манифест** (`application/vnd.oci.image.manifest.v1+json`), не индекс (реестр: MANIFEST_INVALID).
+6. Креды реестра: `docker login registry.kzntsv.site -u books-ci --password-stdin` (актуальный пароль books-ci — в `/opt/books/sched/docker-config.json` на books-vds; в `/root/.docker/config.json` был УСТАРЕВШИЙ → 401 на push).
+
+## Gotcha: большие пуши через traefik умирают
+`docker buildx --push` 1.5-2GB слоёв через `registry.kzntsv.site` (traefik buffering middleware `maxRequestBodyBytes=4GB`) → `Client Closed Request`: traefik буферизует тело в RAM vds-kzntsv (1GB free) + чтение с buildkit-кэша медленное + OOM. curl монолитными PUT/PATCH работает (54MB/s). Связано: [[registry-traefik-buffering-gotcha]].

.wiki/concepts/config-custom-env-mapping-in-mounted-dirs.md

@@ -0,0 +1,22 @@
+---
+title: config-custom-env-mapping-in-mounted-dirs — env бесполезен без mapping-файла
+status: live
+tags: [config, npm-config, env, books, gotcha]
+---
+
+# npm `config` + примонтированный конфиг-дир: env читается только через custom-environment-variables.json
+
+## Проблема (2026-08-23, деплой books)
+Код читает `config.get('sched')` (npm-пакет `config`), env-mapping — `config/custom-environment-variables.json` (`"sched": {"adminUrl": "SCHED_ADMIN_URL", ...}`). В контейнерах books (api/web/task-runner) конфиг-дир — примонтированный (bind `/opt/books/*/config` или named volume), и в нём НЕ было `custom-environment-variables.json` (только `default.json`) → **`config.get('sched')` THROW: "Configuration property sched is not defined"**, даже с env-переменными в стеке.
+
+Причина: маунт **затеняет** файлы из образа; env-mapping работает только если mapping-файл лежит в РАБОЧЕМ конфиг-дире (mounted), не в образе.
+
+## Фикс
+Положить `custom-environment-variables.json` (с sched-mapping) в каждый примонтированный конфиг-дир:
+- slovo: `/opt/books/api/config/`, `/opt/books/task-runner/config/` (host binds)
+- volumes: `books-web-config`, `bookva-api-config`, `bookva-web-config`, `bookva-task-runner-config` — через `docker run --rm -v <vol>:/c -v /tmp:/tmp:ro alpine cp /tmp/file /c/`
+
+Нюансы:
+- mapping **не создаёт** свойство, если его нет в файлах И env-переменная отсутствует: `config.get('sched')` бросит. Нужны оба: mapping-файл + env в стеке.
+- `config` кэшируется на старте процесса — после правки файлов контейнер нужно пересоздать (redeploy).
+- Проверка: `docker exec <ctr> sh -c 'cd /usr/src/app/packages/<svc> && node -e "console.log(JSON.stringify(require(\"config\").get(\"sched\")))"'` (cwd ВАЖЕН — конфиг резолвится от него; `cd /usr/src/app/packages/*` ломается на multi-dir).

.wiki/concepts/registry-traefik-buffering-gotcha.md

@@ -0,0 +1,24 @@
+---
+title: registry-traefik-buffering — большие пуши умирают (Client Closed Request)
+status: live
+tags: [registry, traefik, buffering, push, gotcha]
+---
+
+# Большие (>1.5GB) пуши в registry.kzntsv.site через traefik — умирают
+
+## Симптом
+`docker buildx build --push` (или `docker push`) слоя ~2GB через `registry.kzntsv.site` → `ERROR: unknown: Client Closed Request` (499), обычно после ~5 мин / ~600-800MB. В логах реестра: клиент открывает `POST /v2/<repo>/blobs/uploads/` каждые ~70с, но `PATCH` до реестра НЕ доходит.
+
+## Причина
+Traefik-роут реестра имеет buffering middleware (`traefik.http.middlewares.registry-buffering.buffering.maxRequestBodyBytes=4000000000`): traefik буферизует ВЕСЬ body в RAM vds-kzntsv (7.7GB, свободно ~1GB) перед forwarding. Плюс медленное чтение 2GB слоя из buildkit-кэша на books-vds (3.9GB RAM) → OOM-killer режет процесс → «Client Closed Request». curl с /dev/zero (2GB, chunked, 38с) — проходит (нет дискового рида/кэша).
+
+## Обход (без изменения traefik)
+- Монолитные uploads curl'ом: `POST /v2/<repo>/blobs/uploads/` → `PUT <Location-from-POST>&digest=sha256:<d>` с телом (Content-Length). Мелкие блобы — так, 201.
+- Большой слой: `sync; echo 3 > /proc/sys/vm/drop_caches` → `cat blob | curl -X PATCH -T -` (chunked, стримом) → финальный `PUT <Location-ИЗ-PATCH-ответа>&digest=sha256:<d>` (Location меняется после PATCH!). 202+201.
+- Либо собрать образ ТАМ, где живёт реестр (vds-kzntsv), и пушить напрямую в контейнер реестра (мимо traefik).
+
+## Если понадобится починить навсегда
+Убрать/поднять buffering middleware на роуте registry (Portainer stack 5 на vds-kzntsv, `/opt/stacks/registry/docker-compose.yml`) — traefik будет стримить body. Требует отмашки (инфра-изменение на проде).
+
+## Связано
+[[books-vds-no-gitea-actions]] (локальная сборка + заливка), [[registry-kzntsv-auth-model]] (креды).