✨ feat(deploy): сохранить override и постоянные dev-окружения

Сохранить порядок дополнительных Compose-файлов при обновлении и подключать их помощнику на чтение. Добавить проверки override, постоянных каталогов dev-данных и документацию проекта. Явно задать русский язык в тестах русских подписей.

docs/deployment-overrides.md

@@ -0,0 +1,46 @@
+# Installing behind existing nginx
+
+If nginx already occupies ports 80 and 443, it can serve the Chatballs HTTPS
+domain and forward requests to the installation gateway on a local HTTP port.
+
+Create `compose.override.yaml` next to the release's `compose.yaml`:
+
+```yaml
+services:
+  gateway:
+    ports: !override
+      - "127.0.0.1:8443:80"
+```
+
+Docker Compose 2.24.4 or later is required. `!override` replaces the entire
+port list: the original bindings for 80 and 443 are removed. Here 8443 is an
+internal HTTP port, not an external HTTPS port.
+
+Start the installation with both files:
+
+```bash
+docker compose -f compose.yaml -f compose.override.yaml up -d --wait
+```
+
+The external nginx terminates HTTPS and proxies requests to
+`http://127.0.0.1:8443`, preserving `Host`, forwarding `X-Forwarded-Proto`,
+and supporting WebSocket. The external nginx handles the certificate and
+HTTP → HTTPS redirect. Open the setup wizard on the final HTTPS domain,
+without the internal port.
+
+## Updates from the interface
+
+The updater reads the Compose file list from the running container's labels.
+It replaces the first file with the new release and preserves additional files
+in their original order. This includes the standard `compose.override.yaml`
+and custom filenames explicitly passed with `-f`.
+
+Apply the override when starting the installation. A file that merely sits
+next to the main file but is not part of the running project's configuration
+is not automatically added during an update.
+
+The installation directory and additional files are mounted read-only in the
+update helper. This preserves resolution of `.env`, relative `env_file`
+entries, and configuration paths. Keep override files accessible at the same
+paths. A missing or invalid override stops the update before services are
+restarted. The release overwrites only the main `compose.yaml`.

docs/deployment-overrides.ru.md

@@ -0,0 +1,46 @@
+# Установка за существующим nginx
+
+Если порты 80 и 443 уже заняты nginx, он может обслуживать HTTPS-домен
+Chatballs и передавать запросы шлюзу установки по локальному HTTP-порту.
+
+Создайте рядом с релизным `compose.yaml` файл `compose.override.yaml`:
+
+```yaml
+services:
+  gateway:
+    ports: !override
+      - "127.0.0.1:8443:80"
+```
+
+Требуется Docker Compose 2.24.4 или новее. `!override` заменяет весь список
+портов: исходные публикации 80 и 443 не сохраняются. Здесь 8443 — внутренний
+HTTP-порт, а не внешний HTTPS-порт.
+
+Запустите установку с обоими файлами:
+
+```bash
+docker compose -f compose.yaml -f compose.override.yaml up -d --wait
+```
+
+Внешний nginx завершает HTTPS и проксирует запросы на
+`http://127.0.0.1:8443`, сохраняя `Host`, передавая `X-Forwarded-Proto`
+и поддерживая WebSocket. Сертификат и HTTP → HTTPS редирект обслуживает
+внешний nginx. Открывайте мастер первого запуска по окончательному
+HTTPS-домену без внутреннего порта.
+
+## Обновления из интерфейса
+
+Updater берёт список Compose-файлов из меток работающего контейнера.
+Первый файл заменяется новым релизом; дополнительные файлы сохраняются
+в исходном порядке. Поддерживаются стандартный `compose.override.yaml`
+и файлы с другими именами, явно переданные через `-f`.
+
+Override должен быть применён при запуске установки. Файл, который просто
+лежит рядом, но не входит в конфигурацию работающего проекта, при обновлении
+автоматически не подключается.
+
+Каталог установки и дополнительные файлы доступны помощнику обновления
+только на чтение. Это сохраняет разрешение `.env`, относительных `env_file`
+и путей конфигурации. Файлы override должны оставаться доступными по тем же
+путям. Пропавший или некорректный override останавливает обновление до
+перезапуска сервисов. Релиз перезаписывает только основной `compose.yaml`.

docs/dev-task-runtime.md

@@ -0,0 +1,71 @@
+# Постоянное dev-окружение задачи
+
+Обычная основная копия сохраняет прежние `./data` и Docker secret volumes.
+`CHATBALLS_DEV_DATA_DIR` в `compose.dev.yaml` позволяет разместить PostgreSQL,
+Redis и media вне checkout. В production используются прежние именованные тома.
+
+Для worktree используйте `scripts/task-dev.ps1`. Он требует имя окружения,
+свободный диапазон из шести портов и абсолютный каталог данных вне всех worktree:
+
+```powershell
+./scripts/task-dev.ps1 -Name t-008 -PortBase 18020 -DataDir C:/ChatballsRuntime/t-008
+```
+
+Это запуск существующей базы: без `postgres/PG_VERSION` скрипт остановится.
+Он также проверяет наличие исходных secret volumes проекта `t-008`.
+Имя Compose нельзя менять при переносе данных: оно определяет секреты инстанса.
+
+Для новой реальной установки владелец явно выбирает `-InitializeDatabase`.
+Запуск выполнит штатные миграции; владельца и организацию создают через обычный
+мастер первого запуска. Скрипт не создаёт пользователей или демонстрационные
+данные. Новая установка не является восстановлением старой базы.
+
+Порты: `PortBase` PostgreSQL, `+1` Redis, `+2` backend-app, `+3`
+backend-platform, `+4` frontend, `+5` web-chat. Frontend использует свой
+`backend-app` внутри того же Compose-проекта. Скрипт проверяет настоящий
+`/api/v1/health/ready/` через frontend proxy (БД и Redis).
+
+## Перенос существующих данных
+
+1. Запишите исходное имя Compose и mount paths через `docker inspect`.
+2. Остановите все сервисы, которые пишут в PostgreSQL, Redis и media.
+3. Сделайте резервную копию и проверьте её; копируйте полный `data`, включая
+   PostgreSQL WAL и служебные файлы, в постоянный каталог. Исходник сохраняйте.
+4. Сохраните прежнее имя Compose и все три исходных secret volumes. Не используйте
+   `down -v`, не удаляйте тома и не генерируйте новые пароли для существующей базы.
+5. Задайте `CHATBALLS_DEV_DATA_DIR` и пересоздайте соответствующие сервисы штатным
+   Compose. Проверьте mount paths, readiness и существующие данные/вход.
+
+Если исходная база исчезла вместе с worktree, требуется её резервная копия.
+Восстановление только исходников из Git не возвращает БД и media. Не направляйте
+frontend на другую задачу, чтобы скрыть отсутствие API; общий backend должен
+быть явно согласованной зависимостью с устойчивыми исходниками и данными.
+
+`scripts/start.ps1` и `start.sh` предназначены для основной копии, не для
+одноразовых worktree. Слияние задачи не должно удалять каталог, используемый
+Docker как source mount.
+
+## Действующее общее окружение T-008 (29 сентября 2026)
+
+Frontend T-008 на `http://localhost:5173` явно использует основное окружение:
+API `http://host.docker.internal:8010`, исходники backend из основной копии,
+её существующие `data/postgres`, `data/redis`, `data/media` и исходные секреты.
+Это основная база, а не восстановленная база T-007. Никакие аккаунты и данные
+для этого подключения не создавались. Авторизованные экраны требуют обычного
+входа существующим пользователем основной базы.
+
+Постоянный override вне worktree:
+`C:/Users/drmar/AppData/Roaming/Skaro/runtime/70a06986-4881-4d6d-865c-fa6636fc00b4/T-008/compose.shared.yaml`.
+Из worktree T-008 frontend запускается так (без запуска собственного пустого backend):
+
+```powershell
+$override = 'C:/Users/drmar/AppData/Roaming/Skaro/runtime/70a06986-4881-4d6d-865c-fa6636fc00b4/T-008/compose.shared.yaml'
+$env:INTERNAL_UI_PORT = '5173'
+docker compose -p t-008 -f compose.yaml -f compose.dev.yaml -f $override up -d --no-deps --no-build frontend
+```
+
+Основной frontend отдельно доступен на 5174; Redis основного dev-окружения
+использует host port 16380. При штатном запуске основной копии задайте
+`INTERNAL_UI_PORT=5174` и `REDIS_HOST_PORT=16380`. Старый frontend one-off T-008
+остановлен и сохранён; его ссылка на порт 18010 ведёт в повреждённый T-007.
+Нельзя его запускать одновременно с новым frontend на 5173.