enduro-trails/docs/work-items/ET-001/07-infra-requirements.md

type, work_item_id, version, status, created_at, authors

type	work_item_id	version	status	created_at	authors
infra-requirements	ET-001	1	approved	2026-05-15	agent:architect

Infra Requirements — ET-001

Изменения в enduro.lua требуют пересборки OSRM-графа. Деплой кода без пересборки графа не имеет смысла — старый граф продолжит маршрутизировать через шлагбаумы.

1. Целевая среда

• Хост: mva154 (82.22.50.71)
• Compose stack: /home/slin/enduro-trails/osrm/docker-compose.yml
• Образ: ghcr.io/project-osrm/osrm-backend:v5.27.1 (как сейчас, не менять)
• Профиль: /home/slin/enduro-trails/osrm/enduro.lua (обновляется из infra/osrm/enduro.lua)
• Данные:
  • Вход: /home/slin/enduro-trails/data/region.osm.pbf
  • Промежуточный: /home/slin/enduro-trails/data/enduro.osm.pbf (копия)
  • Граф: /home/slin/enduro-trails/data/enduro.osrm* (несколько файлов)

2. Ресурсные требования к пересборке графа

Параметр	Значение	Источник
Время osrm-extract	~40 мин	измерено на текущей сборке (region.osm.pbf, threads=1)
Время osrm-partition	~3 мин	измерено
Время osrm-customize	~2 мин	измерено
Итого пересборка	~45 мин	укладывается в требование BRD ≤ 60 мин
RAM peak (extract)	~4.5 GB	mem_limit: 5g в compose
Свободная RAM на хосте	≥ 2 GB	сейчас free + buff/cache ≈ 3.1 GB, swap 2 GB → достаточно
Свободное место на диске	≥ 3 GB	для временных файлов extract
Threads	1 (как в текущем compose)	при threads>1 RAM-пик растёт >7 GB → OOM

Threads=1 — не менять без согласования. На хосте 7.7 GB RAM суммарно, остальные сервисы (FastAPI, tile server, nginx) требуют ~2 GB. При threads=1 OSRM укладывается; при threads=2 — риск OOM-kill.

3. Простой сервиса роутинга

Между docker compose down osrm-routed и docker compose up -d osrm-routed сервис /api/route недоступен — клиент получит 502 от nginx.

Этап	Простой /api/route
Запуск osrm-prepare (extract+partition+customize)	0 мин — osrm-routed продолжает работать на старом графе
Restart osrm-routed после готовности нового графа	~10 сек (load графа в память)

Итого простой /api/route ≈ 10 секунд.

Полный downtime в 45 мин не требуется — extract можно запускать рядом с работающим routed, OSRM пишет в новые файлы (*.osrm.fileIndex.tmp и т.д.), затем atomic rename.

⚠️ Исключение: если RAM при одновременной работе osrm-prepare (4.5 GB peak) и osrm-routed (~600 MB) превысит лимит — может включиться swap, что замедлит и пересборку, и работающие запросы. На текущем хосте: 4.5 + 0.6 + 2 (другие сервисы) = 7.1 GB при лимите 7.7 GB. Запас тонкий → окно low-traffic, ночь по МСК.

4. Шаги деплоя (для Operator)

1. Merge PR в trunk.
2. На mva154:

   cd /home/slin/enduro-trails
   # обновить профиль из репо
   cp repo/infra/osrm/enduro.lua osrm/enduro.lua
   # запустить пересборку (новый скрипт из ТЗ)
   ./scripts/rebuild-osrm.sh
   

3. rebuild-osrm.sh выполняет:
   • docker compose --profile prepare up osrm-prepare (45 мин)
   • docker compose restart osrm-routed (10 сек)
4. Smoke-test: curl http://localhost:5559/route/v1/driving/37.6,55.7;37.7,55.8 → 200 + geometry.
5. Прогнать tests/integration/test_routing_barriers.py на test-окружении.

5. Rollback

Профиль перед изменением должен быть сохранён как enduro.lua.bak (уже есть на сервере). Граф — также сохранить:

# перед пересборкой
cp /home/slin/enduro-trails/data/enduro.osrm /home/slin/enduro-trails/data/enduro.osrm.bak.$(date +%Y%m%d)

Откат:

mv /home/slin/enduro-trails/data/enduro.osrm.bak.YYYYMMDD /home/slin/enduro-trails/data/enduro.osrm
cp osrm/enduro.lua.bak osrm/enduro.lua
docker compose restart osrm-routed

Время отката: ~30 сек.

6. Изменения в инфраструктуре (вне ET-001)

• Новых контейнеров не вводится.
• Новых портов не открывается.
• Новых томов не добавляется.
• nginx-конфиг не меняется.
• CI: пересборка графа не входит в pipeline — это ручной шаг Operator. CI только: lint Lua, pytest на mock-OSRM (или против уже-собранного test-графа).

7. Мониторинг

После релиза в течение 48ч наблюдать:

• Доля 404 от /api/route (баланс «обход шлагбаума» vs «маршрут не построен»). Бейзлайн до релиза — ~0.3%. Допустимо до ~2%.
• p95 длины маршрута на типовом наборе из 50 reference-точек (отклонение ≤ +5% от бейзлайна).
• Логи osrm-routed на NoRoute всплески.

Метрики снимаются вручную через логи nginx + ad-hoc скрипт (отдельная задача на дашборд — out of scope ET-001).