vios-build-system · diff

git:20260716.87cbfa5 to git:20260720.a3fbde6

1 added, 1 removed. Audit A to A.

---

description: VIOS build system, container deployment, and common build pitfalls

alwaysApply: true

---

# 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.

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

**Toolchain & base are automatic:** `./build.sh container module=…` auto-builds the compile toolchain + base image on first run (cached afterward, never rebuilt unless deleted). Just run the build directly — do NOT ask the user to build a toolchain first or which toolchain tag to use. First build on a fresh clone is ~10-15 min longer because of this one-time step. For a pre-pulled toolchain, pass `toolchain-image=<ref>` (or set `X86_BUILD_IMAGE`/`AARCH64_CC_IMAGE`) with `no-auto-deps`.

**Registry/tags:** default image tags are local-only (`vios/...`, `nvstreamer`). To publish, pass `image-registry=<ref>` / `nvstreamer-image=<ref>` / `toolchain-image=<ref>` (or the matching env vars) at build time, then `push=1`.

# 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 all` -- one-shot: toolchain → base → all modules + NVStreamer

- `./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 nvstreamer` -- build NVStreamer container

- `./build.sh container ingress` -- build ingress container

- `./build.sh container mcp` -- build MCP gateway container

- `./build.sh toolchain` -- build the compile toolchain only (auto-invoked otherwise); `arch=arm64` for aarch64

- `./build.sh toolchain push=1 toolchain-image=<registry>/vios-build:<tag>` -- build + push toolchain (ask the user for the registry if not given; default tag would push to Docker Hub)

- `./build.sh base-container [push=1 image-registry=<registry>]` -- build (and optionally push) the runtime base image only

- `./build.sh container module=… no-cache` -- force rebuild from scratch (the way to force a toolchain/base rebuild — otherwise cached & skipped)

- `./build.sh container module=… no-auto-deps` -- fail fast if toolchain/base missing (CI / pre-pulled)

- `./build.sh clean` -- clean the current arch's build objects (`arch=arm64` for aarch64). Run only when switching module set or arch; a same-modules rebuild does not need it. Do NOT clean the other arch (it would pull that arch's toolchain image just to delete files).

- `./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.

+ **Deployment mode** (SDRC vs direct) is an **adaptor-independent** toggle selected by the block at the top of `compose.env` (`VST_USE_SDRC`, `COMPOSE_PROFILES`, `NGINX_MODE`). **SDRC mode is now the default** — it adds `sdr-controller` + the init chain for header-routed multi-pod operation (also works single-pod). Direct mode (no SDR/Envoy, single-pod only) is the alternative; deploy it with `oneclick_dc_deployment.py deploy --no-sdrc`, which rewrites `compose.env` to `VST_USE_SDRC=false` / `NGINX_MODE=vst` / cleared `COMPOSE_PROFILES` / stream-processor on `:30001`. SDRC-vs-direct is orthogonal to the `VST_ADAPTOR` (`vst`/`mms`) choice — `vst-sdrc` is **not** an adaptor.

**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.