Quickstart

This guide provides a comprehensive step-by-step walkthrough to help you quickly set up and start using the Warehouse Blueprint.

The Warehouse Blueprint is a video analytics solution that supports real-time object detection, tracking, and analytics. It offers two message broker options to accommodate different deployment scenarios:

• Kafka: High-throughput message broker optimized for datacenter deployments with robust persistence and scalability.
• Redis Streams: Lightweight message broker ideal for edge deployments with minimal memory footprint and low-latency requirements.

Choose the message broker based on your deployment environment: Kafka for centralized datacenter installations, or Redis for distributed edge locations where resources are constrained.

Components Overview

The high-level diagram illustrates the components of the Warehouse Blueprint. The diagram features the 2D, 3D, or MV3DT blueprint. The Agent communicates with the Blueprint’s data services through APIs.

The following diagram shows the major components of the Warehouse Blueprint:

Camera streams are ingested by VST/VMS, processed by RT-CV (perception) and Behavior Analytics microservices, with CV metadata and alerts published to the Message Bus and persisted via Storage Services.

The following diagram shows how AI Agents interact with the Warehouse Blueprint:

The Agent orchestrates MCP servers for Video IO, Video Analytics, and Report Generation, leveraging Nemotron (LLM) and Cosmos-Reason (RTVI-VLM) inference microservices.

Prerequisites

Before you begin, ensure all of the prerequisites are met. See Prerequisites for more details.

Deployment Options

The Warehouse Blueprint offers flexible deployment options with the following profiles:

Supported GPU Hardware

See Hardware Profiles and Deployment Paths for supported profiles, published performance, and GPU placement.

NVIDIA Certified GPU Servers and Workstations

Download Warehouse Artifacts

This section guides you through the steps to download the Warehouse Blueprint artifacts.

Setup NGC Access

# Setup NGC access
export NGC_CLI_API_KEY=<NGC_CLI_API_KEY>
export NGC_CLI_ORG='nvidia'

Download the Deployment Package

Perform this on the machine where you intend to deploy the blueprint.

git clone --branch "v3.3.0" https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization.git
cd video-search-and-summarization
git lfs install
git lfs pull
cd deploy/docker
# This is the path to the deploy/docker directory. Set VSS_APPS_DIR in industry-profiles/warehouse-operations/overrides.env.
#VSS_APPS_DIR="/path/to/deploy/docker"

Warehouse App Data

Warehouse App Data contains sample videos, playback data, runtime directories, and the sample-data license. Calibration files and configuration templates come from the repository. Perception models are downloaded from NGC during deployment using models-download.json; TensorRT engines are built on first run and cached under $VSS_DATA_DIR/models/. MV3DT Compose also stages CLIP-ReID (reid_model.onnx, 1280-D) and SigLIP 2 (siglip_v2_vdeployable_v2.0) under $VSS_DATA_DIR/models/reid on first boot.

The package includes the following MP4 datasets at 1920x1080 and 30 FPS:

The repository includes 2D, 3D, and MV3DT calibration for nv-warehouse-4cams, warehouse-loading-dock-3cams-synthetic, and warehouse-4cams-20mx20m-synthetic, so any of these three datasets can be used with any Warehouse analytics mode. Set NUM_STREAMS to the camera count shown below.

ngc registry resource download-version "nvidia/vss-warehouse/vss-warehouse-app-data:3.3.0"
# OR Manually download the tar file from NGC
# URL https://catalog.ngc.nvidia.com/orgs/nvidia/teams/vss-warehouse/resources/vss-warehouse-app-data?version=3.3.0
# Extract the package
cd vss-warehouse-app-data_v3.3.0
tar -xvf vss-warehouse-app-data.tar.gz
# Set permissions
sudo chmod -R 777 /path/to/vss-warehouse-app-data
# This is the path to the extracted data directory. Set VSS_DATA_DIR in industry-profiles/warehouse-operations/overrides.env.
#VSS_DATA_DIR="/path/to/vss-warehouse-app-data"

Deploy Warehouse Blueprint

Configure Environment settings

This section explains the most commonly edited variables in industry-profiles/warehouse-operations/.env and overrides.env.

Deployment Selection

Select the deployment profile, message broker, and deployment size below. Update the corresponding existing values in industry-profiles/warehouse-operations/overrides.env; do not append duplicate keys. Keep the shipped COMPOSE_PROFILES_WH_* definitions and update the COMPOSE_PROFILES selector that follows them. The three datasets with repository calibration can be selected independently of the analytics mode; set NUM_STREAMS to the selected dataset’s camera count. For 3D, also set DATASET_TYPE as described under Common Variables.

MODE=2d
BP_PROFILE=bp_wh
STREAM_TYPE=kafka
COMPOSE_PROFILES=${COMPOSE_PROFILES_WH_2D}
# Warehouse profiles use SDRC.
VST_USE_SDRC=true
STREAM_PROCESSOR_MODULE_ENDPOINT=http://sdr-controller:10000
VST_NGINX_MODE=vst-sdrc

Hardware Profiles and Deployment Paths

Run nvidia-smi -L to identify the GPU model, then use the hardware tab below to set HARDWARE_PROFILE and the GPU placement for your deployment path.

Set the common deployment variables in industry-profiles/warehouse-operations/overrides.env:

# NVIDIA-hosted endpoint
export NVIDIA_API_KEY="<api-key>"
# OpenAI endpoint (use this instead of NVIDIA_API_KEY)
# export OPENAI_API_KEY="<api-key>"

Container image coordinates are centralized in containers.env and loaded by the deployment command. In your hardware tab:

1. Copy the settings from Hardware Profile into industry-profiles/warehouse-operations/overrides.env. For GB300 and DGX-SPARK, also export the SBSA image-tag suffix as described in the hardware tab.
2. Choose exactly one deployment path and copy its settings into the same file.

Default container image tag

containers.env uses VSS_CONTAINER_TAG as the default tag for all images. Export the tag selected for this documentation branch before choosing a hardware layout:

export VSS_CONTAINER_TAG="3.3.0"

Any service-specific image tag or tag suffix shown inside a hardware tab supersedes or augments this common default. Use the SBSA settings shown in the GB300 and DGX Spark tabs when deploying on those platforms.

# Use RTXPRO6000BW-SE instead for RTX PRO 6000 Blackwell Server Edition.
HARDWARE_PROFILE=RTXPRO6000BW

Elasticsearch ILM policy retention period

To increase the retention period, adjust index lifecycle (ILM) time by setting ELASTICSEARCH_ILM_MIN_AGE in industry-profiles/warehouse-operations/.env (for example 12h or 1d). This value is passed to the Elasticsearch init container when ILM policies are applied.

Default: 4h

ELASTICSEARCH_ILM_MIN_AGE=4h

For how ILM policies are defined and other tuning options, see ELK (Elasticsearch, Logstash, Kibana).

NIM Deployment Modes

The following modes apply to the LLM_MODE environment variable.

Model Configuration

Deploy the Blueprint

Deploy Warehouse Blueprint

cd /path/to/deploy/docker
# Log in to the NGC container registry.
docker login \
    --username '$oauthtoken' \
    --password "${NGC_CLI_API_KEY}" \
    nvcr.io
# Start the blueprint.
docker compose -f compose.yml \
    --env-file containers.env \
    --env-file industry-profiles/warehouse-operations/.env \
    --env-file industry-profiles/warehouse-operations/overrides.env \
    up --detach --pull always --force-recreate --build

docker ps -a

Verify Deployment

1. Verify if containers are in running state:

Verify deployment

docker ps
docker compose ls

2. Check to make sure streams were properly added to VST. To do so, navigate to the VST UI (see endpoint below) and check the Dashboard to confirm your streams are in a healthy state. If you do not see them there, check NVStreamer or your source to make sure they are active.

3. Check vss-rtvi-cv FPS to make sure DeepStream is running properly. View the vss-rtvi-cv logs by running the below command and looking for FPS lines in the logs. Ensure it is running at the desired FPS. If this is lower than expected, make sure your GPU is not oversaturated.

# For 2D/3D Vision AI Profile
docker logs -f vss-rtvi-cv
# For MV3DT Vision AI Profile
docker logs -f vss-rtvi-cv-mv3dt

On first MV3DT boot, wait for appearance ReID before expecting perception FPS. Models download in the one-shot vss-reid-embed-init-mv3dt container (exit 0), then etcd, MinIO, and Milvus must be healthy, then:

docker logs -f vss-reid-embed-mv3dt
curl -sf http://localhost:8088/health/ready

The 300s figure on the ReID health check is a start grace period, not a maximum. Retries continue after that, so first-boot engine build can take longer. Perception does not start until the probe succeeds.

4. Check Kibana for indexed analytics data and alerts. Go to the endpoint listed below and navigate to the dashboard.

5. Check the VSS UI (see endpoint below) and test a few prompts after the system is up for a few minutes and a few alerts are present.

For detailed testing and validation steps, refer to:

• 2D Vision AI Profile
• 2D Vision AI with Agents Profile
• 3D Vision AI Profile
• MV3DT Vision AI Profile
• Troubleshooting Guide

Service Access Points

Once deployed, the following service access points are available:

Teardown the Deployment

To stop and remove the Warehouse Blueprint deployment:

# Stop the running deployment
cd /path/to/deploy/docker
docker compose -f compose.yml \
    --env-file containers.env \
    --env-file industry-profiles/warehouse-operations/.env \
    --env-file industry-profiles/warehouse-operations/overrides.env \
    down
# Alternatively to remove all the containers, images and volume
docker compose -f compose.yml \
    --env-file containers.env \
    --env-file industry-profiles/warehouse-operations/.env \
    --env-file industry-profiles/warehouse-operations/overrides.env \
    down -v --rmi all
# Tear down all dangling volumes
docker volume ls -q -f "dangling=true" | xargs docker volume rm
# Cleanup all data (from deployments directory)
bash scripts/cleanup_all_datalog.sh -e industry-profiles/warehouse-operations/overrides.env

Customization

The Blueprint supports several levels of customization, including but not limited to adding new cameras and updating models. For details, refer to the following sections under the Blueprint deep dive pages:

• 2D Vision AI Profile Customization
• 2D Vision AI with Agents Profile Customization
• 3D Vision AI Profile Customization
• MV3DT Vision AI Profile Customization

Warehouse Blueprint Skill

Agent Skills are reusable capabilities that coding agents such as Claude Code or Codex can load to deploy and operate the VSS Blueprint from natural-language requests. For the Warehouse Blueprint, use the vss-build-vision-ai Skill. It treats Warehouse as a pre-built industry blueprint: it selects a supported Warehouse variant, validates the host and app data, generates a self-contained deployment, brings up the stack, and monitors readiness without requiring the operator to memorize every deployment command.

For the complete VSS Skills catalog and installation model, see Agent Skills.

Installing Skills

Install the Skills the same way as any other VSS Agent Skill. See Installing Skills for the full installation flow.

After installation, start a new coding-agent session before invoking the Skill by name.

Deploy the Warehouse Blueprint

1. Ask your coding agent to deploy the Warehouse Blueprint. For example:

   Deploy Warehouse in 2D mode.
   Deploy the VSS Warehouse Blueprint on this host.
   Deploy Warehouse with the bp_wh profile, the in-stack VSS Agent, and a remote LLM.
   Deploy Warehouse in 3D mode with Kafka, using the extended profile.
   Deploy Warehouse in auto-calibration mode for warehouse-loading-dock-3cams-synthetic.

   Select the deployment variant, service set, and dataset when prompted, and provide any missing credentials.

   

2. Review the proposed architecture and generated configuration.

   

3. Review the pre-flight results and resolve any blockers before deployment. In this example, the NGC key must be replaced.

   

4. Let the Skill deploy the stack and verify container health, active camera streams, and analytics output.

   

After the stack is running, use the Warehouse Blueprint VIOS UI and Kibana UI to verify that the deployment is serving data. Kibana is not available in minimal deployments.

How the Skill Configures and Runs the Deployment

For the Warehouse Blueprint, vss-build-vision-ai loads skills/vss-build-vision-ai/references/profiles/warehouse.md in the VSS Blueprint repository. That reference owns the Warehouse-specific decisions the Skill makes on the operator’s behalf:

• Profile variants - selects bp_wh for MODE=2d only, bp_wh_kafka or bp_wh_redis for MODE=2d|3d|mv3dt, or bp_wh_auto_calib for MODE=auto-calibration, along with the matching Compose profile list. Dataset selection is independent of the analytics mode. For MODE=3d, confirm that the generated override.env sets DATASET_TYPE to the family described under Common Variables. See Deployment Selection.

• Minimal vs extended - for bp_wh_kafka and bp_wh_redis, chooses whether to deploy ELK, Video Analytics API, and monitoring on top of the core CV pipeline. See the Minimal Profile section above for the comparison.

• GPU layout - maps services to host GPU device IDs:

  • RT_CV_DEVICE_ID - GPU for RT-CV/perception.
  • RT_VLM_DEVICE_ID - GPU for rtvi-vlm in the bp_wh 2D agent profile.
  • LLM_DEVICE_ID - GPU for the LLM in bp_wh 2D agent profile when using LLM_MODE=local. This setting is not used when LLM_MODE=remote or LLM_MODE=none.

• LLM placement - for the bp_wh 2D agent profile, keeps a local LLM when requested or selected by default and sizing permits it. It uses a remote endpoint only when the operator requests one or approves it after local sizing fails. For bp_wh_kafka and bp_wh_redis in 2D, 3D, or MV3DT mode, and for bp_wh_auto_calib in auto-calibration mode, it sets LLM_MODE=none.

• App data - asks the operator for an existing Warehouse app-data location or, when explicitly selected, downloads the NGC resource. It sets VSS_DATA_DIR to the extracted vss-warehouse-app-data directory and blocks deployment unless the required directories exist and the selected dataset directory is non-empty.

• Calibration - uses repository calibration for the three shipped datasets. A custom dataset requires calibration generated with vss-generate-video-calibration or a separate MODE=auto-calibration build, placed at the mode-specific repository path before an analytics build is deployed.

• Container image tag - runs a release’s images when you name an image tag in the prompt, or when VSS_CONTAINER_TAG is already exported. Otherwise it uses the containers.env default. See Container image tag.

• Build and validate - writes _builds/<name>/override.env, compose.yml, configurator.env, and resolved.yml. The Skill resolves the Warehouse env layers into resolved.yml, then validates the resolved services, images, bind mounts, mode/profile/service selection, calibration presence, stream count, and GPU placement.

• Bring up and monitor - refreshes registry images and deploys only the standalone _builds/<name>/resolved.yml. It accepts running services and successful one-shot containers, probes selected endpoints, checks active-source liveness, and checks MV3DT BEV Fusion health when applicable before reporting success.

Debugging and Updating Skills

For deployment or runtime failures, consult the Skill’s references/troubleshooting.md. Warehouse-specific configuration, validation, and readiness checks are defined in references/profiles/warehouse.md.

After updating the repository, follow Updating Skills and start a new coding-agent session.

Related Documentation

• Agent Skills - VSS Skills catalog, installation, usage, and update flow.

Brev Launchable

Launchables are a part of NVIDIA Brev that deliver preconfigured, fully optimized compute and software environments.

This deployment uses the Docker Compose deployment method to set up the Warehouse Blueprint.

Link to GitHub Repository used in this launchable.

Launch Blueprint

Prerequisites

Host System Prerequisites

Brev Launchable takes care of the host requirements.

Obtain NGC API Key

Follow How to get an NVIDIA NGC API key.

Deployment Profiles

The launchable notebook uses the same MODE and BP_PROFILE values described in the Deployment Selection section above. It derives STREAM_TYPE from BP_PROFILE: bp_wh_redis uses Redis, and the other profiles use Kafka.

The notebook selects a default dataset and stream count for each mode and profile. To select a different dataset, set SAMPLE_VIDEO_DATASET in Section 1 and update the existing NUM_STREAMS value in industry-profiles/warehouse-operations/overrides.env to match the dataset’s camera count before running Section 9. For 3D, also set DATASET_TYPE to real or synthetic for the selected dataset.

See Deployment Options for full details on each profile.

Steps to Launch the Blueprint

1. Go to the Launchable page.

   

2. Click Deploy Launchable in the upper-right corner.

3. Click Go to Instance Page.

4. After the instance is enabled, click Open Notebook.

   

   Close any warning dialogs that appear in JupyterLab.

5. Open a terminal in JupyterLab and check out the repository reference selected for this documentation build before opening the warehouse launchable notebook:

   cd ~/video-search-and-summarization
   git fetch origin "v3.3.0"
   git checkout --detach FETCH_HEAD

6. Navigate to and open the video-search-and-summarization/deploy/docker/scripts/deploy_warehouse_launchable.ipynb notebook. If it is already open, close and reopen it after checking out the reference so it loads the selected version.

   The Compose files ship in-tree in the video-search-and-summarization repository—there is no separate Compose archive to download. On Brev, the repository is cloned onto the instance automatically; set DEPLOY_SOURCE_PATH in Section 1 to that path (typically ~/video-search-and-summarization).

7. In Section 1, set NGC_CLI_API_KEY and select MODE, BP_PROFILE, and HARDWARE_PROFILE.

8. Run each cell in order and use the URLs printed by Section 11. The notebook prints only the URLs available for the selected profile.

Accessing the UI

Section 11 of the notebook prints the URLs available for the selected profile:

• Agent UI → <secure_link> directly (the HAProxy ingress serves the Agent UI at the root path)
• Kibana → <secure_link>/kibana/ (requires an extended COMPOSE_PROFILES_WH_* service list without the _MINIMAL suffix)
• VIOS (VST) UI → <secure_link>/vst/

For the full set of service access points (including direct ports for Video Analytics API, VA-MCP, and NIM endpoints), see Service Access Points.