Запуск в Docker¶

Docker-режим запускает драйверы, ROS-мост, веб-сервер и модели в одном контейнере. На Linux-хосте нужны Docker Engine и Compose. Docker Engine должен работать на том же компьютере, где находятся исходники, камеры и каталог данных. ROS, Node.js и Python приложения устанавливаются в образ. Управление выполняется той же командой smartcamera.

Подготовка¶

Сначала установите CLI, затем проверьте Docker:

docker version
docker compose version
docker info

Если Docker отсутствует, smartcamera docker-setup запускает установочный скрипт через sudo для Ubuntu 24.04. Скрипт использует официальный APT-репозиторий Docker. Конфликтующие пакеты не удаляются автоматически. Уже установленный Docker не переустанавливается. Если после установки пользователь не имеет доступа к сокету, настройте доступ по инструкции Docker, войдите в сеанс заново и повторите команду. CLI не добавляет пользователя в группы самостоятельно.

Для других дистрибутивов установите Docker по официальной инструкции. Далее CLI может использовать работающий Docker Engine. Docker Desktop на macOS и Windows не проверен для проброса камер и ROS DDS.

CPU: сборка и первый запуск¶

smartcamera docker-setup --yes --profile cpu

smartcamera run --detach

smartcamera status

Сборка выполняется из каталога исходников, выбранного при установке CLI или переданного через --source. Используются также локальные незакоммиченные файлы. При сборке контейнера используются эти исходники; повторного скачивания проекта нет.

Первая сборка скачивает базовые образы, системные пакеты и PyTorch. Это требует интернета, нескольких гигабайт свободного места и заметного времени. Готовый образ получает локальное имя smartcamera:cpu; он никуда не публикуется.

Откройте http://127.0.0.1:8000. Первый запуск без добавленных камер нужен для проверки веб-сервера. run --detach ожидает успешного HTTP health-check; если контейнер не готов за 120 секунд, команда завершится ошибкой. Посмотрите журнал:

smartcamera logs --follow
smartcamera stop

После неудачного запуска stop удаляет контейнер и служебное состояние CLI. Пользовательский каталог данных сохраняется. Команда run без --detach после проверки готовности показывает журнал; Ctrl+C останавливает контейнер.

USB-камера V4L2¶

По умолчанию контейнеру не передаётся ни одна камера. Разрешите нужное устройство:

smartcamera stop
smartcamera configure --yes --device /dev/video0
smartcamera run --detach

--device можно повторить для нескольких устройств. Переданный список заменяет предыдущий. --clear-devices очищает список. Контейнер получает UID/GID пользователя хоста и группы выбранных устройств. На хосте у пользователя тоже должен быть доступ к камере.

В веб-интерфейсе добавьте V4L2-камеру с тем же путём /dev/video0. Если используете /dev/v4l/by-id/..., передайте именно этот путь через --device и укажите его в конфигурации камеры. После переподключения V4L2-камеры остановите и снова запустите контейнер: номер устройства и привязка Docker могли измениться.

RealSense¶

Для доступа к USB-шине:

smartcamera stop
smartcamera configure --yes --usb
smartcamera run --detach

В этом режиме монтируется /dev/bus/usb и разрешаются USB character devices (major 189). Режим privileged не используется. --usb даёт доступ к USB-шине, а не только к одному серийному номеру. Конкретную камеру затем выбирают в SmartCamera. Для отключения доступа используйте configure --yes --no-usb.

Правила udev устанавливаются на хосте, не внутри контейнера. На Docker-хосте без локальной установки SmartCamera настройте правила RealSense отдельно:

curl --fail --location \
  https://raw.githubusercontent.com/IntelRealSense/librealsense/v2.50.0/config/99-realsense-libusb.rules \
  --output /tmp/99-realsense-libusb.rules
sudo install -m 644 /tmp/99-realsense-libusb.rules /etc/udev/rules.d/99-realsense-libusb.rules
sudo udevadm control --reload-rules

Затем переподключите камеру. Образ собирается с librealsense 2.50.0, как профиль L515 в проекте. Для камер, использующих V4L2-узлы, также передайте соответствующие /dev/videoN через --device. Возможность горячего переподключения зависит от SDK, ядра и устройства; после потери доступа пересоздайте контейнер.

NVIDIA GPU¶

Установите на хосте совместимый NVIDIA-драйвер и NVIDIA Container Toolkit. Профиль проекта использует PyTorch с CUDA 13.0; драйвер должен поддерживать эту версию. Наличие установленного CUDA Toolkit на хосте само по себе не означает, что контейнеру доступен GPU.

nvidia-smi
smartcamera stop
smartcamera docker-setup --yes --profile cuda
smartcamera run --detach

Образ получает имя smartcamera:cuda. Compose запрашивает NVIDIA GPU, а entrypoint проверяет torch.cuda.is_available() перед запуском ROS. Если GPU недоступен, контейнер останавливается с объяснением в журнале. Сборка CUDA-образа не требует доступа к GPU; проверка выполняется именно при запуске.

Профиль cuda подготавливает окружение, но не меняет устройство у уже сохранённых запусков моделей. В карточке модели на камере выберите Устройство → cuda:0 и примените настройки, как описано в запуске модели.

Механизм передачи GPU описан в документации Compose. CPU-образ не запрашивает NVIDIA runtime.

ROS 2 и сеть¶

Используется сеть хоста (network_mode: host), чтобы контейнер и ROS-узлы хоста могли участвовать в DDS discovery. Сопоставление портов -p не требуется. Порт 8000 должен быть свободен. Настройте одинаковый ROS_DOMAIN_ID:

smartcamera stop
smartcamera configure --yes --domain-id 10
smartcamera run --detach
export ROS_DOMAIN_ID=10
source /opt/ros/jazzy/setup.bash
ros2 topic list

Для своих программ на хосте установите и соберите smart_camera_interfaces. Примеры команд и QoS приведены в разделе ROS 2. Для доступа к веб-интерфейсу с другого компьютера задайте configure --yes --host 0.0.0.0; приложение будет слушать сетевые интерфейсы хоста.

Постоянные файлы¶

Каталог данных монтируется по тому же абсолютному пути внутри контейнера, чтобы пути к снимкам и моделям не менялись только из-за перехода в Docker. Исходники не монтируются поверх собранного приложения. После изменения кода выполните stop, rebuild, затем run.

Настройки веб-интерфейса могут содержать другой каталог записи. В контейнере доступны только смонтированные пути: выбирайте папки внутри каталога данных. Перенос существующей установки с моделями и калибровками требует проверки абсолютных путей; CLI не переписывает их автоматически.

Для просмотра Compose-конфигурации без создания файлов:

smartcamera run --mode docker --dry-run

Сгенерированная конфигурация рабочего запуска хранится рядом с настройками CLI. Команды stop и logs используют её, поэтому завершают именно зарегистрированный экземпляр. Перед изменением настроек или сборкой выполните stop.