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

.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).