Add city gameplay, snapshot migrations, administration and Compose operations

deploy/README.md

@@ -0,0 +1,75 @@
+# Запуск через Compose
+
+Из корня репозитория, с работающим Docker Engine:
+
+```sh
+cp .env.example .env
+docker compose config --quiet
+docker compose build
+# Необязательно: подготовить город из локальной OSM-выгрузки.
+docker compose run --rm --no-deps app node --import tsx tools/demo.ts
+docker compose up -d --wait
+```
+
+Открыть `http://localhost:3000/?play`. Можно создать город через интерфейс.
+Города и сохранения находятся в отдельных постоянных томах `cities` и `saves`.
+Пересборка и `docker compose down` сохраняют тома. `down -v` удаляет их.
+Существующий каталог города нельзя перезаписывать, пока на него ссылаются комнаты.
+
+Приложение работает от пользователя `node`, с лимитами памяти, CPU,
+процессов и ротацией логов. Значения `.env.example` рассчитаны на старт с
+1000 жителями; миллион жителей и пять комнат требуют замера и настройки.
+Порт по умолчанию доступен локально. Для внешнего доступа измените
+`CITYGEN_HOST_IP` или используйте HTTPS reverse proxy с WebSocket.
+Встроенный лимит создания видит IP TCP-соединения, поэтому за прокси он
+общий для всех посетителей; недоверенные X-Forwarded-For не используются.
+
+Остановка посылает SIGTERM; сервер завершает комнаты и ждёт запись снимков
+(до 120 секунд). Перед обновлением:
+
+```sh
+docker compose stop
+# Сделать резервную копию ОБОИХ томов средствами Docker-хоста.
+docker compose build
+docker compose up -d --wait
+```
+
+Проверка: `docker compose ps`, `docker compose logs --tail=100 app`,
+`curl --fail http://localhost:3000/health`. Миграция комнат v1→v2 выполняется
+при открытии комнаты; неизвестная версия остаётся на диске с ошибкой.
+Квота `CITYGEN_SAVE_QUOTA_BYTES` включает все снимки и временный новый файл
+до ротации: оставьте запас минимум на один полный снимок. При переполнении
+запись отклоняется, прежние снимки сохраняются. Квота относится к снимкам;
+объём городов ограничивайте средствами Docker-хоста.
+
+## Администрирование
+
+Задать `CITYGEN_ADMIN_TOKEN` случайной строкой минимум из 32 символов в `.env`
+и пересоздать контейнер. Пустое значение отключает API. `.env` игнорируется Git
+и не попадает в build context. `/?admin` показывает комнаты, использование
+диска и ошибки несовместимых снимков, позволяет сохранить активную комнату.
+Ответ приходит после записи. Токен остаётся только в памяти страницы.
+
+API: `GET /api/admin`, `POST /api/admin/rooms/{id}/checkpoint`,
+заголовок `Authorization: Bearer <token>`. Привилегии оператора не выдаются
+игрокам и создателям комнат. Удаление миров/городов через API не предусмотрено.
+
+## Мониторинг
+
+```sh
+docker compose --profile monitoring up -d --wait
+```
+
+Prometheus на `http://localhost:9090` опрашивает `/metrics` каждые 5 секунд,
+хранит до 7 дней / 1 ГБ. `alerts.yml` содержит правила недоступности,
+тиков дольше 50 мс и ошибок сохранения. Предупреждения видны в Prometheus;
+внешние уведомления требуют отдельного Alertmanager. Зафиксирована
+[версия 3.15.1](https://github.com/prometheus/prometheus/releases/tag/v3.15.1).
+
+Метрики: комнаты/игроки, сущности, последний/максимальный тик,
+байты рассылки, ошибки и последний успешный тик сохранения. Ошибки снимков,
+медленные тики, запуск/остановка пишутся JSON-строками в stderr.
+
+Без Engine можно проверить `docker compose --profile monitoring config --quiet`.
+Полный smoke-test контейнера после запуска: `/health`, вход двух клиентов,
+команда «Обед», остановка/запуск и проверка восстановленного состояния.