chatballs/docs/dev-task-runtime.md

Постоянное dev-окружение задачи

Обычная основная копия сохраняет прежние ./data и Docker secret volumes. CHATBALLS_DEV_DATA_DIR в compose.dev.yaml позволяет разместить PostgreSQL, Redis и media вне checkout. В production используются прежние именованные тома.

Для worktree используйте scripts/task-dev.ps1. Он требует имя окружения, свободный диапазон из шести портов и абсолютный каталог данных вне всех worktree:

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

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