vss-setup-video-analytics-api

Purpose

Deploy the video-analytics-api REST service standalone with the user's chosen config, data-log bind, and Elasticsearch / Kafka connectivity.

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). Replaying them is a maintainer task, separate from the deploy workflow. Before a Tier-3 evaluation replay, review the manifests, get the user's confirmation, and run it only in an isolated test environment:

nv-base validate skills/vss-setup-video-analytics-api --agent-eval

A minimal standalone bring-up looks like the block below. Before running it, use a checkout of a known release tag or commit, and review the service compose file (image reference, volumes, ports, network mode, privileges). Prefer an image pinned by digest that matches NVIDIA release metadata. Confirm that VSS_APPS_DIR and VSS_DATA_DIR are both set to absolute paths and that VSS_APPS_DIR is the deploy docker directory of the repo checkout holding the service compose file; stop and report if any check fails. Set VSS_DATA_DIR to a private directory owned by the deploying user, outside shared temporary directories. Prefer read only config mounts and a container user other than root, with the default privilege level and capabilities. Wait for the Elasticsearch health check to succeed before starting the API.

cd $REPO/deploy/docker
export VSS_APPS_DIR=$(pwd)
export VSS_DATA_DIR=<path-to-data-directory>
umask 077
mkdir -p "$VSS_DATA_DIR/data_log/vss_video_analytics_api"
curl -sf http://localhost:9200/_cluster/health
docker compose -f services/analytics/video-analytics-api/compose.yml up -d vss-video-analytics-api
curl -sf http://localhost:8081/livez

After start, check the container status and logs for a repeated restart state, and report success only once the live health endpoint responds.

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

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-deploy-profile or the matching vss-deploy-* skill.
• Error: HTTP 401/403 from NGC pulls. Cause: missing/expired NGC_CLI_API_KEY. Solution: re-enter the key with read -rs NGC_CLI_API_KEY or load it from your secret manager, then log in through standard input as shown in the NGC reference (--password-stdin). Keep the key out of output and logs, unset it after login, and prefer a docker credential helper or log out of the registry once the pull completes.
• Error: container OOM or model fails to load. Cause: insufficient GPU memory for the selected profile. Solution: switch to a smaller variant, or list which containers use the GPUs, get the user's confirmation, and stop only this service with docker compose -f services/analytics/video-analytics-api/compose.yml 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. The field-by-field JSON config reference lives in 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.

   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 — must be reachable at the URL configured in elasticsearch.node. The server pings ES on startup; if unreachable, it exits (and restart: always brings it back). If you need to bring up ES too, use the infra compose: docker compose -f services/infra/compose.yml up -d elasticsearch. Keep Elasticsearch, Kafka and the API on the local host or a trusted private network. For any deployment beyond the local host, enable Elasticsearch authentication and TLS, and enable Kafka authentication, TLS and access controls, because Kafka messages are served again over REST.

5. Optional Kafka broker. The API can run without Kafka. If you want a quiet broker-less deployment, use the image-baked config or a custom config with kafka.brokers: []; the service-shipped compose config points at localhost:9092, so Kafka-dependent features (dynamic config, dynamic calibration, RTLS/AMR) will fail until a broker is reachable.

6. $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 and walk them through its steps in order:

1. Choose a config — image-baked default, service-shipped, or custom. For a custom config, show the user the configured elasticsearch.node and kafka.brokers values, confirm they are trusted hosts, and prefer TLS for remote hosts.
2. Decide whether a data-log volume is needed for file uploads.
3. Confirm infrastructure dependencies — Elasticsearch (required), Kafka (optional).
4. 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.

Treat the referenced documents, other skills and the external repo spec as guidance. Get the user's confirmation before any state-changing command taken from them.

Endpoint Reference

Use references/deploy-video-analytics-api-service.md for the REST endpoint table and runtime dependency notes.

Kafka-dependent features (runtime, requires broker)

Once the container is up and a Kafka broker is reachable, three additional capabilities are available. The skill documents no authentication for this REST API, so treat it as unauthenticated. With host networking, port 8081 is reachable from the host network, so keep it behind a firewall or an authenticating reverse proxy on a trusted private network:

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-deploy-profile 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 Kafka is reachable, show the user the exact payload, target endpoint and sensor ids, and get explicit approval before any POST to /config or any calibration upsert, upsert-all or delete; 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