vios-build-system git:20260716.bdadf73A

Immutable. This exact content is served forever at /api/v1/blob/3c70838b49198a17.

---
description: VIOS build system, container deployment, and common build pitfalls
alwaysApply: true
---

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# Build System

Use `./build.sh` -- **do not invoke `make` directly**. Run `./build.sh help` for all options. Use `/build-help` skill if unsure which flags to use.

Valid modules: `sensor`, `rtspserver`, `recorder`, `livestream`, `replaystream`, `streambridge`, `storage`, `streamprocessing`

**Registry:** Always use the GitLab registry (`gitlab` flag) for dev and testing. NVCR is for production/release only.

# Build and Deploy Workflow

VIOS runs inside Docker containers. The dev build-deploy cycle is:

1. **Build + containerize**: `./build.sh container module=<modules>` (compiles C++, packages, creates Docker image)
2. **Deploy via docker-compose**: `python3 deployment/stream-processing/oneclick_dc_deployment.py` (non-interactive one-click deployment by default; pass `--interactive` to opt in to prompts)

## IMPORTANT: Auto-run build and deploy commands

When the user asks to build, deploy, stop, or redeploy -- run the commands immediately without asking for confirmation. Always use `--force` on the deployment script to skip the "existing deployment detected" prompt. Do NOT ask the user "shall I proceed?" or "want me to run this?" -- just execute.

- Build: `./build.sh container module=<modules>` -- run directly, long-running (~20min for all modules)
- Deploy: `python3 deployment/stream-processing/oneclick_dc_deployment.py deploy --force` -- run directly
- Stop: `python3 deployment/stream-processing/oneclick_dc_deployment.py stop` or `stop vst` -- run directly
- Full cycle (build + deploy): run build first, then deploy sequentially -- no confirmation needed

## build.sh Options

- `./build.sh module=sensor` -- plain build (compile only, no packaging)
- `./build.sh package module=sensor,rtspserver` -- build + package into deployable archives
- `./build.sh container module=sensor,rtspserver,recorder,livestream,replaystream,storage,streambridge,streamprocessing` -- build + package + create Docker containers for all modules
- `./build.sh container module=streamprocessing push=1` -- build + push to registry
- `./build.sh container tag=mytag module=sensor` -- custom image tag
- `./build.sh container ingress` -- build ingress container
- `./build.sh container mcp` -- build MCP gateway container
- `./build.sh debug module=sensor` -- debug build

## One-Click Deployment Script

**Script:** `deployment/stream-processing/oneclick_dc_deployment.py`

Deploys VIOS microservices via docker-compose. Non-interactive by default; smart defaults are applied automatically. Uses `<action> [target]` positional form or `--target <target>` flag form.

Targets: `vst` (default; alias `vios` accepted, stream-processor at `deployment/stream-processing/docker-compose/`), `nvstreamer`, `all`.

```
python3 deployment/stream-processing/oneclick_dc_deployment.py deploy --force                        # deploy VIOS (default target)
python3 deployment/stream-processing/oneclick_dc_deployment.py deploy --target nvstreamer --force    # deploy NVStreamer only
python3 deployment/stream-processing/oneclick_dc_deployment.py deploy --target all --force           # deploy VIOS + NVStreamer
python3 deployment/stream-processing/oneclick_dc_deployment.py stop                                  # stop all services
python3 deployment/stream-processing/oneclick_dc_deployment.py stop vst                              # stop only VIOS
python3 deployment/stream-processing/oneclick_dc_deployment.py stop nvstreamer                       # stop only NVStreamer
python3 deployment/stream-processing/oneclick_dc_deployment.py stop --clean                         # stop and remove persistent data
python3 deployment/stream-processing/oneclick_dc_deployment.py deploy --fresh-start --force          # clean start
python3 deployment/stream-processing/oneclick_dc_deployment.py deploy --with-monitoring --force      # deploy with Grafana/Prometheus
python3 deployment/stream-processing/oneclick_dc_deployment.py deploy --pull-always --force          # pull latest images
python3 deployment/stream-processing/oneclick_dc_deployment.py deploy --interactive                  # opt in to prompts
```

**Key paths (stream-processor / default):**
- Compose files: `deployment/stream-processing/docker-compose/docker-compose.yaml`
- Config: `deployment/stream-processing/docker-compose/configs/`
- Compose env: `deployment/stream-processing/docker-compose/compose.env`
- SDRC overlay: `deployment/stream-processing/docker-compose/sdrc/` (only active when `VST_USE_SDRC=true` + `COMPOSE_PROFILES=sdrc` in `compose.env`)
- NVStreamer compose: `deployment/stream-processing/docker-compose/nvstreamer/`

**Deployment mode** (SDRC vs direct) is selected by the toggle block at the top of `compose.env`. Direct mode is the default — 4 containers, single-pod, no SDR/Envoy. SDRC mode adds `sdr-controller` + the init chain for header-routed multi-pod operation.

**Access URLs (after deploy):**
- VIOS UI: `http://<HOST_IP>:30888/vst/#/dashboard`
- Grafana: `http://<HOST_IP>:3000` (with `--with-monitoring`)

**VIOS containers (direct mode):** `centralizedb`, `vst-ingress`, `sensor-ms`, `streamprocessing-ms-1`

**Extra containers in SDRC mode:** `redis`, `sdr-controller`, `sdrc-init-dirs`, `sdrc-render-config`

## Debugging: Source changes require container rebuild

Since VIOS runs in Docker, editing source files alone does NOT affect the running service. The full cycle is:
1. Edit source files
2. `./build.sh container module=<affected_modules>` -- rebuilds container image
3. `python3 deployment/stream-processing/oneclick_dc_deployment.py deploy --force` -- redeploys with new image
4. Check logs: `sudo docker compose -f docker-compose.yaml --env-file ./compose.env logs -f` (from `deployment/stream-processing/docker-compose/`)

# Common Build Pitfalls

1. **Use `./build.sh`, not `make`** -- arch detection, Docker, and module flags won't be set correctly otherwise.
2. **Wrong arch prebuilts** -- `PREBUILT_DIR` is `prebuilts/$(arch)/`; wrong arch links silently against the wrong libs.
3. **Missing module define** -- features gated by a `CPPFLAGS` define silently no-op if `module=` is omitted.
4. **Kafka consumer depends on `notification_proto`** -- enforced in the Makefile; do not remove it.
5. **OpenTelemetry on aarch64/SBSA** -- `USE_OTEL=0`; OTEL headers are not available there.
6. **Multi-module plain build** -- `module=a,b` without `package` or `container` will error out.
7. **Source edits not visible at runtime** -- VIOS runs in Docker; must rebuild container and redeploy.