gx
fbe1d18c39
- docs/troubleshooting.md — 13 секций с реальными grабельками которые мы прошли: cudaIpcOpenEventHandle invalid device context (pid namespace), s6-overlay vs pid share, scale_cuda missing (cuda-llvm + stdbit.h glibc 2.36), libcuframes not found install paths, ffbuild/ missing source, GMP no working compiler (long-long reliability), zlib.net deprecated URL, RTSP/RTP UDP docker NAT, gitea actions Node version - docs/architecture.md — Appendix A "Production deployment notes" с реальными observations после 24h+ run: что подтвердилось, что доработали, что не учли - docs/requirements.md — production deployment matrix + Docker namespace requirements таблица (cross-container CUDA IPC требует 5 условий) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
217 lines
10 KiB
Markdown
217 lines
10 KiB
Markdown
# System Requirements
|
||
|
||
Минимальные требования для использования cuframes — как для **сборки**, так и
|
||
для **runtime**. Если что-то из этого не выполняется — библиотека либо не
|
||
скомпилируется, либо не запустится.
|
||
|
||
## 1. Hardware
|
||
|
||
### GPU
|
||
|
||
- **NVIDIA GPU** (vendor lock — CUDA IPC is NVIDIA-specific)
|
||
- **Compute Capability ≥ 7.5** (Turing или новее)
|
||
- Поддерживается: RTX 20xx / 30xx / 40xx / 50xx, Quadro RTX, A-серия (A40/A100), H-серия (H100), GH200
|
||
- Не поддерживается: Pascal (GTX 10xx, P100) и старше — CUDA 13 drop'нул support
|
||
- На границе: Volta (V100, Titan V) — sm_70, технически CUDA 13 deprecates, но `cudaIpc*` API работает
|
||
- **CUDA IPC support** — все GPU с CC ≥ 3.0 имеют CUDA IPC, но мы ограничены CUDA 13 toolkit'ом
|
||
- **Single GPU per producer/consumer pair** — CUDA IPC handles **не работают** между разными devices. Если у вас 2× GPU и публикуете на GPU 0, consumer должен быть на GPU 0
|
||
- **Linux only** — CUDA IPC использует POSIX shared memory + Unix domain sockets. На Windows не работает (даже WSL2 — untested, скорее всего не работает из-за hypervisor isolation)
|
||
|
||
### VRAM
|
||
|
||
Зависит от использования:
|
||
|
||
| Setup | Минимум VRAM |
|
||
|---|---|
|
||
| 1 камера FullHD NV12, ring=2 | **~10 MB** (2 × 3MB frame + overhead) |
|
||
| 1 камера 4K NV12, ring=4 | **~50 MB** |
|
||
| 16 камер FullHD NV12, ring=4 | **~200 MB** |
|
||
| 16 камер 4K NV12, ring=4 | **~800 MB** |
|
||
|
||
Это **только** для cuframes ring buffers. Add VRAM для самого decoder'а
|
||
(FFmpeg/NVDEC), inference моделей и т.д.
|
||
|
||
Для domashno-CCTV setup'а (16 камер) на RTX 3060 12GB / 4060 16GB / 5090 32GB —
|
||
**с большим запасом**.
|
||
|
||
### RAM
|
||
|
||
- **~64 MB** host memory на publisher + ~10 MB на subscriber
|
||
- POSIX shared memory `/dev/shm/cuframes-<key>` фиксированно ≤ 8 KB
|
||
- Unix socket buffers — kernel-managed, ~32 KB
|
||
|
||
Реально библиотека «бесплатна» по RAM. CUDA driver сам потребляет ~200 MB.
|
||
|
||
### CPU
|
||
|
||
- Любой x86_64 (CUDA не работает на ARM кроме Jetson — отдельная история)
|
||
- Никаких специальных требований к ядрам — hot-path не CPU-bound
|
||
- Минимум 2 cores рекомендуется (один для main thread, один для async subscriber thread)
|
||
|
||
## 2. Software (host system)
|
||
|
||
### Operating System
|
||
|
||
- **Linux** (kernel ≥ 5.4)
|
||
- Tested distros:
|
||
- Ubuntu 22.04 LTS (CUDA 12.x)
|
||
- Ubuntu 24.04 LTS (CUDA 13.x) — **рекомендуется**
|
||
- Debian 12 (bookworm)
|
||
- RHEL 9 / Rocky Linux 9
|
||
- Не поддерживается: Alpine (musl-libc вместо glibc — несовместимо с NVIDIA libs)
|
||
|
||
### NVIDIA Driver
|
||
|
||
- **Driver ≥ 555** для CUDA 13 runtime (рекомендуется)
|
||
- **Driver ≥ 525** для CUDA 12 runtime (минимум — если используете старый toolkit)
|
||
- Tested:
|
||
- 555.x, 565.x, 575.x, 595.x — известно работают
|
||
|
||
Driver version и CUDA runtime — отдельные вещи. cuframes использует CUDA runtime
|
||
API (`cudart`), который linked в нашу .so, а driver обеспечивает kernel-level
|
||
CUDA. См. [NVIDIA compat table](https://docs.nvidia.com/deploy/cuda-compatibility/).
|
||
|
||
### Userspace
|
||
|
||
- **glibc ≥ 2.31** (Ubuntu 20.04+, Debian 11+)
|
||
- **CUDA Toolkit 12.0+** (для сборки) — 13.0+ рекомендуется
|
||
- POSIX shared memory (`/dev/shm`) — mount'нут как tmpfs, обычно по умолчанию
|
||
- POSIX threads (`pthread`) — обычно есть везде
|
||
|
||
## 3. Software (build-time)
|
||
|
||
Для **сборки cuframes** из исходников (если не используете готовые Docker
|
||
images / .deb пакеты):
|
||
|
||
| Tool | Минимум | Рекомендуется |
|
||
|---|---|---|
|
||
| CUDA Toolkit | 12.0 | **13.0+** (содержит `cudaIpc*` improvements) |
|
||
| GCC | 11 (для C++17) | 12+ |
|
||
| Clang | 14 | 17+ |
|
||
| CMake | 3.20 | 3.28+ |
|
||
| Ninja | (опционально, любая) | |
|
||
| pkg-config | любая | |
|
||
| Python | 3.10 (для bindings, Phase 3+) | 3.12 |
|
||
| FFmpeg | 4.4 (для filter, Phase 2+) | **7.x** (target) |
|
||
|
||
Build dependencies устанавливаются через apt:
|
||
|
||
```bash
|
||
sudo apt install build-essential cmake ninja-build pkg-config \
|
||
nvidia-cuda-toolkit nvidia-cuda-dev \
|
||
libavcodec-dev libavformat-dev libavutil-dev libavfilter-dev
|
||
```
|
||
|
||
## 4. Docker (опционально, рекомендуется)
|
||
|
||
Если используете готовые images (`ghcr.io/<org>/cuframes-ffmpeg:N` или
|
||
`cuframes-frigate:0.17`) или dev-контейнер:
|
||
|
||
| Component | Минимум |
|
||
|---|---|
|
||
| Docker Engine | 24.x |
|
||
| nvidia-container-toolkit | 1.14+ |
|
||
| docker compose | v2.20+ |
|
||
|
||
Container setup требования:
|
||
- `--gpus all` (или specific `--gpus device=0`)
|
||
- `--ipc=shareable` (для cross-container CUDA IPC) или `--ipc=host`
|
||
- `--shm-size=2gb` (default 64 MB не хватит для CUDA IPC handles)
|
||
- Bind-mount `/run/cuframes` для Unix sockets
|
||
|
||
См. `docker/README.md` для готовых compose-файлов.
|
||
|
||
### Cross-container CUDA IPC
|
||
|
||
Чтобы producer в одном container'е делился frame'ами с consumer в другом:
|
||
- Оба container'а должны быть в **одном IPC namespace**:
|
||
- Variant A: `--ipc=container:<other-container-name>` для secondary
|
||
- Variant B: `--ipc=host` (менее изолировано)
|
||
- Оба должны видеть тот же `--gpus` device
|
||
- `/run/cuframes` должен быть shared (volume) между ними
|
||
- `/dev/shm` — каждый container имеет свой, но через IPC namespace memory-region shareable
|
||
|
||
Kubernetes:
|
||
- Поды должны быть в одном Pod (sidecars), shared `volumeMounts: emptyDir` для `/run/cuframes`
|
||
- IPC namespace — pod-level `shareProcessNamespace: true` + `hostIPC: true` для cross-pod (security implications)
|
||
|
||
## 5. Не поддерживается
|
||
|
||
Явно out-of-scope для v0.1:
|
||
|
||
| | Почему |
|
||
|---|---|
|
||
| AMD GPU (ROCm) | Аналог HIP IPC существует, но API отличается. Возможный roadmap для v1.x |
|
||
| Intel GPU (Arc / Xe) | Нет аналога CUDA IPC в Level Zero (на 2026-05) |
|
||
| Windows | CUDA IPC использует POSIX SHM + Unix sockets — Linux primitives |
|
||
| macOS | Apple deprecated NVIDIA support с Mojave; CUDA not available |
|
||
| WSL2 | CUDA IPC через WSL hypervisor — недокументированное поведение, untested |
|
||
| Jetson | Имеет CUDA, но cross-process через NVMM (другой API); может работать но not tested |
|
||
| Multi-GPU | producer и consumer должны быть на одном CUDA device — CUDA IPC ограничение |
|
||
| Multi-host | CUDA IPC localhost-only; RDMA / GPUDirect — другой scope |
|
||
|
||
## 6. Quick check
|
||
|
||
Проверить совместимость хоста (требует только bash + nvidia-smi):
|
||
|
||
```bash
|
||
# CUDA driver и compute capability
|
||
nvidia-smi --query-gpu=name,driver_version,compute_cap --format=csv,noheader
|
||
|
||
# Минимум: driver ≥ 525 (CUDA 12) или ≥ 555 (CUDA 13)
|
||
# compute_cap ≥ 7.5
|
||
|
||
# Linux kernel
|
||
uname -r # ≥ 5.4
|
||
|
||
# glibc
|
||
ldd --version | head -1 # ≥ 2.31
|
||
|
||
# /dev/shm size (для CUDA IPC handles)
|
||
df -h /dev/shm # минимум 256 MB свободно
|
||
```
|
||
|
||
## 7. Тестировано на
|
||
|
||
Phase 0 PoC (2026-05-14):
|
||
- **Hardware:** NVIDIA RTX 5090 (Blackwell, sm_120, 32 GB), Intel/AMD CPU x86_64
|
||
- **Driver:** 595.58.03
|
||
- **CUDA:** 13.0.88 (внутри dev container на базе `nvidia/cuda:13.0.3-cudnn-devel-ubuntu24.04`)
|
||
- **OS host:** Ubuntu 24.04, kernel 6.17.x
|
||
- **Docker:** 29.1.3 с nvidia-container-runtime
|
||
- **Container:** Ubuntu 24.04 + GCC 13 + Clang + CMake 3.28 + Ninja
|
||
|
||
## Production deployment matrix (v0.1.0)
|
||
|
||
Что подтверждено в 24h+ production run:
|
||
|
||
| Слой | Версия | Comments |
|
||
|---|---|---|
|
||
| NVIDIA driver | 555+ | минимум для CUDA 12 user runtime |
|
||
| CUDA toolkit (build) | 12.4 (Debian 12 / Ubuntu 22.04) либо 13.0 (Ubuntu 24.04) | toolkit для builder image, не runtime |
|
||
| GPU | RTX 5090 (sm_120) | проверено; раньше — sm_75 минимум |
|
||
| Builder OS | Ubuntu 22.04 (glibc 2.35) | forward-compat с Debian 12 runtime |
|
||
| Runtime OS (Frigate) | Debian 12 (glibc 2.36) | base image Frigate `stable-tensorrt` |
|
||
| Runtime OS (cctv-backend) | Ubuntu 22.04 либо Debian 12 | matched с builder |
|
||
| Docker | 29.1.x | для buildx |
|
||
| docker buildx | v0.34.0+ | `apt install docker-buildx-plugin` либо manual install из GH releases |
|
||
| nvidia-container-toolkit | 1.14+ | для `runtime: nvidia` |
|
||
|
||
## Docker namespace requirements (cross-container CUDA IPC)
|
||
|
||
Для consumer'а который подключается к publisher'у в **другом** container'е:
|
||
|
||
| Что нужно | Как настроить |
|
||
|---|---|
|
||
| `/dev/shm` shared (header + ring metadata) | `ipc: container:<publisher>` либо `ipc: shareable` у publisher + same у consumer |
|
||
| `/proc` visibility (CUDA IPC peer validation) | `pid: container:<publisher>` |
|
||
| `/run/cuframes/*.sock` доступен | volume mount `cuframes_sock:/run/cuframes:ro` |
|
||
| GPU access | `runtime: nvidia` + `NVIDIA_VISIBLE_DEVICES=all` |
|
||
| Socket file permissions | `user: root` либо chmod в publisher |
|
||
|
||
**Все 5** должны быть выполнены. Подробности — [docs/troubleshooting.md](troubleshooting.md).
|
||
|
||
**Special case: s6-overlay containers (Frigate, linuxserver.io stack)**: `pid:` share **невозможен** — s6-overlay требует PID 1. Workaround: только `ipc:` + race window connect. См. troubleshooting.
|
||
|
||
Дополнительный target matrix будет в CI после Phase 4 (см. [ROADMAP.md](../ROADMAP.md)).
|