# Docker for cuframes

Все сборки и тесты делаются в Docker. Хостовый CUDA toolkit не нужен —
только NVIDIA driver + nvidia-container-toolkit.

## Развёртывание dev-окружения

```bash
# Один раз (поднимет dev-контейнер на фоне)
docker compose -f docker/docker-compose.dev.yml up -d

# Войти в контейнер
docker compose -f docker/docker-compose.dev.yml exec dev bash
```

После `up -d` контейнер `cuframes-dev` живёт пока его не остановят. Repo
смонтирован в `/workspace`.

Проверка что CUDA видна:

```bash
docker compose -f docker/docker-compose.dev.yml exec dev nvidia-smi
docker compose -f docker/docker-compose.dev.yml exec dev nvcc --version
```

## Что внутри

| Компонент | Версия | Зачем |
|---|---|---|
| Ubuntu | 24.04 | base |
| CUDA Toolkit | 12.4.1 | для `nvcc`, headers, runtime libs |
| cuDNN | 9 | для возможных bindings к ONNX |
| GCC | 12 | стандартный для Ubuntu 24.04 |
| Clang + clang-format + clang-tidy | системные | code style + static analysis |
| CMake | системный (≥3.28) | build |
| Ninja | системный | быстрее make |
| FFmpeg dev headers | системные (6.x) | для linking при разработке filter |
| Python 3 + dev | системный (3.12) | bindings (Phase 3) |
| Profiling | valgrind, gdb, strace, ltrace | debug-набор |

## Что снаружи (на хосте)

Требуется:
- NVIDIA driver ≥ 555 (для CUDA 12.4)
- [nvidia-container-toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)
- Docker Engine с `--gpus` поддержкой
- Каталог `/run/cuframes` (создаётся compose'ом с rw-доступом, либо `sudo mkdir -p /run/cuframes && sudo chown $USER /run/cuframes`)

## Ограничения / нюансы

- **`shm_size: 2gb`** — `/dev/shm` контейнера, нужен для CUDA IPC handles
  и producer/consumer shared memory rings. Default 64 MB не хватит.
- **`ipc: shareable`** — позволяет связывать namespace с другими контейнерами
  через `ipc: "container:cuframes-dev"`. Нужно для cross-container CUDA IPC.
- **`SYS_PTRACE` cap + `seccomp:unconfined`** — для gdb / strace inside.
  Снимать в production-builds.
- Sysctl / ulimits — bind-mount файла `/etc/security/limits.conf` в init не
  гарантирует применения (зависит от docker config). Если CUDA-IPC даст
  `EMFILE` — поднять host-side `ulimit -n 65536` перед `docker compose up`.

## Полезные команды (внутри контейнера)

```bash
# Build cuframes (когда появится CMakeLists.txt)
cmake -B build -S . -G Ninja
cmake --build build -j

# Run tests
ctest --test-dir build --output-on-failure

# Phase 0 spike измерения
./build/tools/spike/pingpong_producer cam_test &
./build/tools/spike/pingpong_consumer cam_test
```

## Distribution / production images

Это **dev-окружение**. Production-images (для FFmpeg-with-cuframes-plugin,
Frigate drop-in) — отдельные Dockerfiles в `docker/ffmpeg-cuframes/` и
`docker/ffmpeg-cuframes-frigate/`, появятся в Phase 4.