vss-setup-video-analytics-api

## Purpose Deploy the video-analytics-api REST service standalone with the user's chosen config and data-log bind. The service exposes port 8081 and `/livez` only after Elasticsearch, the `insertion-timestamp-pipeline`, and, when `STREAM_TYPE=kafka`, the configured Kafka topic requirements are ready. ## Instructions Follow the routing tables and step-by-step workflows below. Each section that ends in *workflow*, *quick start*, or *flow* is intended to be executed top-to-bottom. Detailed reference material lives in `references/`. ## Examples Worked end-to-end examples are kept under `evals/` (each `*.json` manifest contains a runnable scenario). Run a Tier-3 evaluation to replay them: ```bash nv-base validate skills/deployment/vss-setup-video-analytics-api --agent-eval ``` A minimal standalone bring-up looks like: ```bash cd $REPO/deploy/docker export VSS_APPS_DIR=$(pwd) export VSS_DATA_DIR=${VSS_DATA_DIR:-/tmp/vss-data} mkdir -p "$VSS_DATA_DIR/data_log/vss_video_analytics_api" docker compose -f services/analytics/video-analytics-api/compose.yml up -d vss-video-analytics-api curl -sf http://localhost:8081/livez ``` Follow [`references/deploy-video-analytics-api-service.md`](references/deploy-video-analytics-api-service.md) for the full workflow (config source, data-log bind, infrastructure dependencies, REST endpoints). For the field-by-field JSON config reference, see [`references/configuration.md`](references/configuration.md). ## Limitations - Requires the matching VSS profile / microservice to be deployed and reachable from the caller. - NGC-hosted models and NIMs may be subject to rate-limits, GPU memory requirements, and license restrictions. - Concurrency, GPU memory, and storage limits depend on the host hardware and the profile's compose file. ## Troubleshooting - **Error**: REST call returns connection refused. **Cause**: target microservice not running. **Solution**: probe `/docs` or `/health`; redeploy via `vss-build-vision-ai` or the matching `vss-deploy-*` skill. - **Error**: HTTP 401/403 from NGC pulls. **Cause**: missing/expired `NGC_CLI_API_KEY`. **Solution**: `docker login nvcr.io` and re-export the key before retrying. - **Error**: container OOM or model fails to load. **Cause**: insufficient GPU memory for the selected profile. **Solution**: switch to a smaller variant or free GPUs via `docker compose down`. # VSS Setup Video Analytics API — Standalone Deploy **just** the `vss-video-analytics-api` container (the Node.js REST API from the upstream `video-analytics-api` repo), not as part of the full warehouse blueprint stack. The full operational walkthrough — config-source options, data-log volume behavior, infrastructure dependencies, REST API endpoints, deploy + verify, troubleshooting — lives in [`references/deploy-video-analytics-api-service.md`](references/deploy-video-analytics-api-service.md). The field-by-field JSON config reference lives in [`references/configuration.md`](references/configuration.md). This SKILL.md only handles routing and prerequisites. ## When to use - "Deploy video analytics api" / "run video-analytics-api standalone" - "I just want to run the REST API, not the full stack" - "Use my own video-analytics-api config" - "Point the API at a different Elasticsearch / Kafka" - "Start the API without Kafka" / "run the API broker-less" - "Check what REST endpoints are available" ## Prerequisites 1. **Repo checkout** with `$VSS_APPS_DIR` pointing at `<repo>/deploy/docker/`. Required by the service compose's volume binds. 2. **NGC credentials** — `$NGC_CLI_API_KEY` set so docker can pull the image. See [`references/ngc-api-key-registry-login.md`](references/ngc-api-key-registry-login.md). > **Secure-handling note for `NGC_CLI_API_KEY`**: this key is a > long-lived credential that pulls all NVIDIA private images > available to your NGC org. Never commit the key, never paste it > into chat, never store it in `/tmp`. Read it interactively > (`read -rs NGC_CLI_API_KEY`) or load it from your secret manager > (Vault, AWS Secrets Manager, sealed-secrets) at deploy time. > Write any derived `.env` files with `umask 077` + `chmod 600`, > add them to `.gitignore`, and rotate the key on a defined > cadence and after every host decommission. If it has ever been > exposed (host snapshot, shared screen, ticket attachment), > rotate immediately. 3. **Docker runtime** — Docker Engine **28.3.3** with Docker Compose plugin **v2.39.1+**. Verify with `docker --version` and `docker compose version`. 4. **Elasticsearch and ingest pipeline** — the endpoint in `elasticsearch.node` must be reachable and contain `insertion-timestamp-pipeline`. Elasticsearch port availability alone is insufficient: the API deliberately waits for that pipeline before binding port 8081. When using the infra compose, start both `elasticsearch` and `elasticsearch-init-container`. 5. **`STREAM_TYPE`** — Compose passes this environment variable to the API. It accepts only `kafka` or `redis`; unset defaults to `kafka`, and any other value makes the API exit at startup. With `STREAM_TYPE=kafka`, the API waits for configured Kafka topics. With `STREAM_TYPE=redis`, it skips Kafka startup work and topic readiness gates; the API does not create a Redis client. 6. **Kafka configuration when `STREAM_TYPE=kafka`.** With `kafka.brokers: []` or `null`, Kafka startup work is skipped. With brokers configured, the API waits before listening until `mdx-notification`, `mdx-amr`, and at least one `mdx-rtls*` topic exist. The service-shipped config enables Kafka, so provision those topics when selecting Kafka. 7. **`$VSS_DATA_DIR` for the default compose.** The base compose bind-mounts `$VSS_DATA_DIR/data_log/vss_video_analytics_api` for multipart upload handling and file-backed assets such as calibration images. Set the directory to a writable host path and pre-create it, or remove that mount if image uploads are not needed. If any required prerequisite fails, surface the gap before going further. ## Workflow Hand the user [`references/deploy-video-analytics-api-service.md`](references/deploy-video-analytics-api-service.md) and walk them through its steps in order: 1. Choose `STREAM_TYPE`: `kafka` or `redis`; omit it only to use the Kafka default. 2. Choose a config — image-baked default, service-shipped, or custom. 3. Decide whether a data-log volume is needed for file uploads. 4. Confirm readiness dependencies — Elasticsearch plus `insertion-timestamp-pipeline`; and, only for `STREAM_TYPE=kafka` with configured brokers, the required topics. 5. Deploy + verify with `docker compose up` and health check. The compose-file edits, config options, deploy + verify commands, REST API endpoint table, and troubleshooting table all live in that reference — don't duplicate them here. ## Endpoint Reference Use [`references/deploy-video-analytics-api-service.md`](references/deploy-video-analytics-api-service.md) for the REST endpoint table and runtime dependency notes. ## Kafka-dependent features (runtime, requires `STREAM_TYPE=kafka` and non-empty `kafka.brokers`) When `STREAM_TYPE=kafka` and `kafka.brokers` is non-empty, the container does not become live until those brokers and the required topics are available. Once it is live, three additional capabilities are available: ### Dynamic config The API acts as the **producer** for dynamic config updates. When an operator POSTs to `/config`, the API publishes an `upsert` message to the `mdx-notification` topic with Kafka key `behavior-analytics-config`. The downstream `behavior-analytics` container consumes this and ACKs back. The API also handles the bootstrap flow — when `behavior-analytics` starts, it publishes a `request-config` message, and the API replies with `upsert-all` containing the latest verified config from Elasticsearch. Consumer-side validation, ACK semantics, and the full wire contract are documented in the `vss-setup-behavior-analytics` dynamic-config reference. ### Dynamic calibration The API produces calibration update notifications on `mdx-notification` with Kafka key `calibration`. Supports `upsert-all` (full snapshot), `upsert` (per-sensor merge), and `delete` (per-sensor removal). The downstream `behavior-analytics` container consumes these and applies them to the live calibration. Consumer-side validation and per-action policy are documented in the `vss-setup-behavior-analytics` dynamic-calibration reference. ### RTLS / AMR The API consumes real-time location (`mdx-rtls`) and AMR (`mdx-amr`) messages from Kafka and exposes them via REST endpoints. ## Routing rules - If the user wants "the full stack" (UI / agent / perception): hand off to `vss-build-vision-ai` with profile `warehouse` (or `alerts`). Don't run this skill in parallel. - If the user wants to deploy the analytics pipeline (behavior creation, incident detection): hand off to `vss-setup-behavior-analytics`. - If the user wants to publish a runtime config / calibration update through the REST API: confirm `STREAM_TYPE=kafka` and Kafka are reachable, then use the `/config` or calibration endpoints and point them at the behavior-analytics dynamic-update references for the consumer wire contract. - If the user wants to understand the dynamic config / dynamic calibration wire contract from the **consumer** (behavior-analytics) side: point them at the `vss-setup-behavior-analytics` dynamic-config and dynamic-calibration references. - If the user wants to query or interact with the REST API endpoints: the deploy reference endpoint table covers what's available. For the full OpenAPI spec, see `src/app/specification/openapi.json` in the `video-analytics-api` repo. bump:1