wiki/tasks/flightradar24/docs/VM_SETUP.md

Инструкция: создание VM для RTL-SDR ingest-контура

1. Цель

Поднять на PVE отдельную VM, в которую пробрасывается RTL-SDR по USB, после чего внутри VM разворачивается Docker Compose стек с PostgreSQL/PostGIS, capture, preprocess и API.

2. Рекомендуемый профиль VM

Ограничения проекта:

• CPU: до 6 vCPU
• RAM: 10–12 GB
• SSD: 80–100 GB

Рекомендация по стартовому размеру

Если нет явного дефицита ресурсов на хосте:

• 4 vCPU
• 10 GB RAM
• 80 GB SSD

Если хост позволяет и нужен запас:

• 6 vCPU
• 12 GB RAM
• 100 GB SSD

3. ОС

Рекомендуемая ОС:

• Debian 12 minimal

Причина:

• предсказуемая база для Docker/PostgreSQL
• меньше лишнего, чем в desktop-образах
• удобно держать long-running сервисы

4. Настройки VM в PVE

4.1 Общие параметры

• Name: fr24-adsb или fr24-ingest
• Machine: q35
• BIOS: SeaBIOS
• CPU type: host
• Disk bus: VirtIO SCSI
• Network model: VirtIO
• QEMU guest agent: enabled
• Ballooning: disabled или очень консервативно

4.2 Диск

• один системный диск на 80–100 GB
• включить Discard / SSD emulation, если storage позволяет
• не дробить диск без необходимости

4.3 Сеть

• подключить к основному bridge PVE
• лучше использовать DHCP reservation или статический IP
• имя хоста зафиксировать заранее, чтобы не плодить путаницу в compose и мониторинге

5. Установка ОС

1. Создать VM в PVE
2. Подключить ISO Debian 12
3. Установить minimal system
4. Включить SSH server
5. Создать обычного пользователя для администрирования
6. После первого boot обновить систему

6. Базовые пакеты внутри VM

После установки:

• qemu-guest-agent
• docker.io или Docker Engine
• docker compose plugin
• git
• curl
• ca-certificates
• gnupg
• lsb-release
• usbutils
• jq
• chrony или аналогичный time sync

7. Подготовка каталогов

Рекомендуемая структура на VM:

• /srv/fr24/
• /srv/fr24/postgres/
• /srv/fr24/data/
• /srv/fr24/logs/
• /srv/fr24/config/

Смысл:

• отдельно держать данные и логи
• не сваливать всё в home пользователя
• проще backup/restore

8. USB passthrough для RTL-SDR

8.1 Принцип

RTL-SDR подключён к физической машине по USB, а в VM он должен быть проброшен как USB-устройство.

8.2 Рекомендация

• использовать постоянный способ привязки устройства: по USB port или by-id, а не по случайному bus number
• после reboot хоста и VM устройство должно подниматься без ручной переконфигурации

8.3 Проверка в VM

Внутри VM проверить:

• lsusb
• dmesg | tail
• rtl_test или аналогичный тест захвата

Если устройство не видно:

• проверить, не занял ли его хост
• проверить настройки passthrough в PVE
• переподключить устройство через интерфейс PVE

9. Docker Compose подготовка

Перед запуском стека внутри VM:

1. Создать рабочую директорию проекта
2. Подготовить .env отдельно от репозитория
3. Создать volume для PostgreSQL
4. Подготовить network для compose
5. Проверить, что контейнеры смогут обращаться друг к другу по service name

10. Проверка после создания VM

Минимальный чек-лист:

• VM загрузилась после установки ОС
• SSH доступен
• qemu-guest-agent работает
• RTL-SDR виден внутри VM
• Docker и Compose работают
• диск и RAM соответствуют лимитам
• каталог /srv/fr24 создан
• время синхронизировано

11. Что делать дальше после создания VM

После VM setup передать работу Dev-агенту на:

• Docker Compose стек
• PostgreSQL/PostGIS
• capture/preprocess/API контейнеры
• healthchecks
• backup/restore
• мониторинг

12. Критерий готовности VM

VM считается готовой, если:

• RTL-SDR доступен внутри VM
• Docker Compose запускается без ошибок
• есть место под PostgreSQL volume
• система переживает reboot и сохраняет USB passthrough
• VM готова принимать конфигурацию от Dev-агента