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:

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

A minimal standalone bring-up looks like:

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