VSS Deploy

Purpose

Deploy any VSS profile (

base

search

lvs

warehouse

alerts

edge

) using a compose-centric workflow: build env overrides, generate resolved compose (dry-run), review, then deploy. This SKILL.md covers the cross-profile concerns (profile routing, prerequisites, NGC, GPU setup, and the deploy/teardown flow). Profile-specific service lists, sizing, env recipes, endpoints, and debugging live in per-profile reference docs — load the one that matches the user's intent.

Helper script:

run_script("scripts/normalize_resolved_yml.py", "<resolved.yml>")

normalizes a

docker compose config

dry-run dump for diff-friendly review during Step 3c. All other deployment work goes through

compose

dev-profile.sh

Available Scripts

Script	Purpose	Arguments
`scripts/normalize_resolved_yml.py`	Strip optional `depends_on` entries for services filtered out of `resolved.yml` before deploy.	Path to `resolved.yml`

Profile Routing

Match the user's request to a profile, then load that profile's reference for sizing, services, env recipes, and debugging.

User says	Profile	Reference
"deploy vss" / "deploy base"	`base`	`references/base.md`
"deploy alerts" / "alert verification" / "real-time alerts" / "deploy for incident report"	`alerts`	`references/alerts.md`
"deploy lvs" / "video summarization"	`lvs`	`references/lvs-profile.md`
"deploy search" / "video search"	`search`	`references/search.md`
"deploy warehouse" / "warehouse blueprint" / "vss warehouse"	`warehouse`	`references/warehouse.md`
"debug warehouse" / "warehouse not working" / "warehouse FPS low" / "warehouse BEV out of sync"	`warehouse` (debug)	`references/warehouse-debug.md`

Edge hardware routing (DGX Spark, AGX/IGX Thor): see

references/edge.md

. DGX Spark uses the Spark Nano 9B standalone local LLM on port

; AGX/IGX Thor uses the Edge 4B standalone vLLM fallback.

Each profile's reference owns its sizing table. Don't pick a deployment shape from this file — open the profile reference and check minimum GPU count for the host's hardware against the (mode × platform) matrix there.

Instructions

The deployment flow is always: copy

.env

generated.env

, apply overrides, dry-run compose into

resolved.yml

, review, normalize, deploy, then wait for readiness.

bash

# 1. cp dev-profile-<profile>/.env dev-profile-<profile>/generated.env  (clean copy)
# 2. Apply env overrides to generated.env  (source .env stays untouched)
# 3. docker compose --env-file generated.env config > resolved.yml      (dry-run)
# 4. Review resolved.yml
# 5. docker compose --env-file generated.env -f resolved.yml up -d

The source

.env

is treated as read-only defaults committed to the repo. The skill's per-deploy working copy is

generated.env

— same pattern

dev-profile.sh

uses internally. This keeps the checked-in

.env

clean across iterations.

Prerequisites

Repo path — find
```
video-search-and-summarization/
```
on disk. Check
```
TOOLS.md
```
if available.
NGC CLI & API key — see
```
references/ngc.md
```
. Confirm
```
$NGC_CLI_API_KEY
```
is set.
System prerequisites (GPU driver, Docker, NVIDIA Container Toolkit, kernel sysctls) — full checks in
```
references/prerequisites.md
```
. Canonical hardware/driver matrix is the VSS prerequisites page.

Pre-flight check

Run before every deploy. The full system checklist and remediation steps live in

references/prerequisites.md

. For DGX Spark / IGX Thor / AGX Thor, also run the cache-cleaner check in

references/edge.md

Detect sudo mode first. Several pre-flight remediations and the edge cache-cleaner installer call

sudo

. If the host requires a sudo password, those steps will silently no-op under

sudo -n

and leave the deploy in a half-prepared state.

bash

if sudo -n true 2>/dev/null; then
  echo "passwordless sudo — pre-flight will auto-install missing pieces"
else
  echo "sudo requires password — pre-flight will NOT auto-install; hand commands to the user"
fi

When sudo needs a password, the skill must not run privileged installers itself. Surface the copy-pasteable command block from

references/prerequisites.md

to the user with a "run this once and confirm" handoff, then resume after the user replies.

Minimum smoke test (must succeed):

bash

nvidia-smi --query-gpu=index,name --format=csv,noheader
docker info 2>/dev/null | grep -qi runtimes \
  && docker run --rm --gpus all ubuntu:22.04 nvidia-smi >/dev/null 2>&1 \
  && echo "nvidia runtime OK"

If the smoke test fails, do not proceed; open

references/prerequisites.md

for the remediation tree.

Model Selection

```
$LLM_REMOTE_URL
```
/
```
$VLM_REMOTE_URL
```
if the user asks for remote
```
$NGC_CLI_API_KEY
```
(local NIMs) or
```
$NVIDIA_API_KEY
```
(remote)

If no combination on this host satisfies the profile's sizing requirements, stop and report the blocker — don't silently pick another shape.

Edge shared mode is platform-specific. On DGX Spark, run
nvcr.io/nim/nvidia/nvidia-nemotron-nano-9b-v2-dgx-spark:1.0.0-variant
as a standalone local NIM on port
30081
and point the agent at it with
LLM_MODE=remote
. On AGX/IGX Thor, keep using the Edge 4B standalone vLLM fallback with
HF_TOKEN
. Full recipes are in
references/edge.md
.

Deployment Flow

Always follow this sequence. Never skip the dry-run.

Step 0 — Tear down any existing deployment + clear data volumes

If a deployment already exists, tear it down AND clear stale data volumes before redeploying.

Full procedure lives in

references/teardown.md

Step 0a — Credentials gate (run before any env mutation)

Validate every credential the chosen profile needs before Step 1c copies

.env

generated.env

. A 401 here is a 30-second failure; the same 401 inside a NIM cold-start is a 10–20 min failure. Run the discovery and probe flow in

references/credentials.md

, then map the result against the chosen mode: missing or invalid required credentials are blockers, optional credentials are not.

Step 1 — Gather context

Before building env overrides, confirm:

Value	How to determine
Profile	Match user intent to the routing table above. Default: `base`
Repo path	Find `video-search-and-summarization/` on disk
Hardware	`nvidia-smi --query-gpu=name,memory.total --format=csv,noheader`
LLM/VLM placement	Cross-reference available GPUs against the chosen profile's Minimum GPU count table
API keys	`NGC_CLI_API_KEY` for local NIMs, `NVIDIA_API_KEY` for remote
`HOST_IP`	`hostname -I \| awk '{print $1}'` — the host's primary internal IP
`EXTERNAL_IP`	Browser-reachable host/IP. On Brev, use the secure-link domain (see `references/brev.md` ).
`HAPROXY_PORT`	Browser-facing ingress port. Default `7777` ; ensure it is free.

Before

docker compose up

, verify

EXTERNAL_IP

HAPROXY_PORT

VSS_PUBLIC_HOST

, and

VSS_PUBLIC_PORT

are populated with browser-reachable values. Otherwise the stack may appear healthy while UI/API/VST links 404 or loop through Cloudflare Access.

Step 1b — Prepare the data directory

Layout (asset paths, ownership, mount points, profile-specific subdirs) is documented in

references/data-directory.md

. Read that file before deploying for the first time on a host or when changing profiles.

FORBIDDEN:
chown -R ubuntu:ubuntu $VSS_DATA_DIR
(or any recursive chown).
This is "good housekeeping" to a shell-admin instinct but is the deploy-breaking command in this stack. You will observe a "healthy" deploy (containers Up, endpoints 200) while the video pipeline is silently broken. Use
chmod -R 777
on the specific subdirs documented in
data-directory.md
— nothing else.

Step 1c — Initialize

generated.env

The skill's per-deploy working copy. Always start from a fresh copy of the source

.env

— never mutate the source.

bash

PROFILE=base
ENV_SRC=$REPO/deploy/docker/developer-profiles/dev-profile-$PROFILE/.env
ENV_GEN=$REPO/deploy/docker/developer-profiles/dev-profile-$PROFILE/generated.env

cp "$ENV_SRC" "$ENV_GEN"

All subsequent writes (Brev

EXTERNAL_IP

, the env_overrides dict from Step 2) go to

$ENV_GEN

$ENV_SRC

is read-only from here on.

Step 1d — If deploying on Brev, set

EXTERNAL_IP

to the secure-link domain

Read

BREV_ENV_ID

from

/etc/environment

and write

EXTERNAL_IP

into

generated.env

(NOT

.env

). Full secure-link behavior and troubleshooting are in

references/brev.md

bash

brev_env_id=$(awk -F= '/^BREV_ENV_ID=/ {gsub(/"/, "", $2); print $2; exit}' /etc/environment)
sed -i "s|^EXTERNAL_IP=.*|EXTERNAL_IP=7777-${brev_env_id}.brevlab.com|" "$ENV_GEN"

Step 2 — Build env_overrides

Produce an

env_overrides

dict from the user request and the gathered context: choose remote/local LLM/VLM, set credentials, point at endpoints, set platform-specific flags. The full mapping (every override key, when it applies, defaults, profile-specific differences) lives in

references/env-overrides.md

. Each profile reference has worked examples for that profile's common scenarios.

Step 3 — Apply overrides + dry-run

Working env file:

<repo>/deploy/docker/developer-profiles/dev-profile-<profile>/generated.env

(created in Step 1c).

Two env files, distinct roles.
.env
— read-only defaults, checked in. Don't mutate it from the skill.
generated.env
— the skill's per-deploy working copy. All overrides (the dict from Step 2, plus the Brev
EXTERNAL_IP
from Step 1d) land here.
--env-file
always points at this file. Post-deploy verifiers should also read from
generated.env
for the actually-deployed values — see Debugging a Deployment.
generated.env
matches the convention
dev-profile.sh
uses internally — it's a per-invocation scratchpad regenerated by
cp .env generated.env
each run.

bash

# (Step 1c already ran: cp $ENV_SRC $ENV_GEN)

# Apply the env_overrides dict from Step 2 to generated.env
# (read lines, update matching keys, append new keys, write)
# Example:
#   sed -i "s|^LLM_MODE=.*|LLM_MODE=remote|" "$ENV_GEN"
#   sed -i "s|^LLM_BASE_URL=.*|LLM_BASE_URL=http://localhost:30081|" "$ENV_GEN"

# Resolve compose
cd $REPO/deploy/docker
docker compose --env-file $ENV_GEN config > resolved.yml

The resolved YAML is saved to

<repo>/deploy/docker/resolved.yml

Step 3b — Verify resolved.yml has no unexpanded ${...} tokens

Unexpanded

${VAR}

tokens in

resolved.yml

mean compose did not see those env values. Diagnostic procedure and common culprits live in

references/troubleshooting.md

Step 3c — Strip dangling optional

depends_on

from resolved.yml

MUST run after Step 3, before Step 5. Skipping this aborts the deploy:

Normalize - drop optional dependencies for services filtered out from resolved.yml

bash

# From the repo root
uv run skills/vss-deploy-profile/scripts/normalize_resolved_yml.py "$REPO/deploy/docker/resolved.yml"

uv

isn't on the host, install it once with

curl -LsSf https://astral.sh/uv/install.sh | sh

(no root needed). Re-validate before

up -d

bash

docker compose -f "$REPO/deploy/docker/resolved.yml" config --quiet && echo "resolved.yml OK"

If validation still fails after the normalizer runs, capture the error and inspect — that's a different bug (a dependency that's not optional, or another schema violation), not the dangling-depends_on case.

Step 4 — Review

Show the user a summary of what will be deployed:

Profile name and hardware
LLM/VLM models and mode (local/remote/local_shared)
Services that will start
GPU device assignment
Key endpoints (UI port, agent port)

Ask: "Looks good — deploy now?" and wait for confirmation before Step 5.

Exception — autonomous mode. If the user's request already asks you to run autonomously (e.g. "deploy X autonomously", "run without confirmation", "non-interactive"), skip the confirmation prompt and proceed straight to Step 5. This path exists so automated eval / CI invocations don't hang waiting for a human reply they'll never get. In all other cases, a human must approve.

Step 5 — Deploy

bash

cd $REPO/deploy/docker
docker compose --env-file $ENV_GEN -f resolved.yml up -d

--env-file
is mandatory. Without the same
generated.env
used in Step 3,
COMPOSE_PROFILES
may be unset and
up -d
can exit 0 with zero selected services.

Do NOT use
--force-recreate
on retries. It destroys already-warm NIM containers, forcing another 3–5 min torch.compile + CUDA-graph capture per NIM. If the previous
up -d
partially failed, fix the root cause (usually perms or an env typo) and just re-run
up -d
— Docker will re-create only the containers whose config changed or that are down.

docker compose up -d

only creates containers; it does not wait for internal services to finish warming. Never declare deploy success until the readiness gates pass.

Step 5b — Wait until the stack is actually healthy

Gate 0 — container count must be > 0. Refuse to proceed past

up -d

until compose started the expected services:

bash

expected=$(docker compose --env-file $ENV_GEN -f resolved.yml config --services | wc -l)
actual=$(docker compose -f resolved.yml ps -q | wc -l)
[ "$actual" -gt 0 ] && [ "$actual" -ge "$expected" ] \
  || { echo "FAIL: expected $expected services, got $actual — re-check Step 5 --env-file"; exit 1; }

Cold deploys can take 10–20 min. The full readiness procedure lives in

references/readiness.md

, and each profile reference lists the required endpoints. Never declare deploy done after
up -d
; only after every documented endpoint succeeds.

Tear Down

bash

cd $REPO/deploy/docker
docker compose -f resolved.yml down

For switching profiles or recovering from a partial deploy, follow the full procedure in

references/teardown.md

Debugging a Deployment

Use this workflow when the user asks to "debug the deploy", "verify it's working", "why is the agent not responding", or similar. The goal is to confirm the full video-ingestion-to-agent-answer path, not just that containers are "Up".

Each profile reference has a Debugging section listing the exact commands and failure-mode table for that profile.

Quick checks (all profiles)

bash

# 1. All expected containers Up
docker ps --format 'table {{.Names}}\t{{.Status}}'

# 2. Agent API + UI responding
curl -sf http://localhost:8000/docs >/dev/null && echo "agent OK"
curl -sf http://localhost:3000/ >/dev/null && echo "ui OK"

# 3. VLM NIM responding (base/lvs profiles)
curl -sf http://localhost:30082/v1/models | python3 -m json.tool

# 4. LLM NIM responding
curl -sf http://localhost:30081/v1/models | python3 -m json.tool

End-to-end video sanity check

After the quick checks above pass, drive a real query through the agent — e.g. ask it over the REST API or UI to describe a video you've uploaded to VST. If the agent returns a non-empty answer, the upload → ingest → inference → reply path is healthy. If it fails,

docker logs vss-agent

shows which stage tripped.

Examples

Base profile, remote models: route to
```
base
```
, copy
```
dev-profile-base/.env
```
to
```
generated.env
```
, set
```
LLM_MODE=remote
```
/
```
VLM_MODE=remote
```
, dry-run, normalize, deploy, then verify
```
/docs
```
and UI.
Search profile on RTX: route to
```
search
```
, follow
```
references/search.md
```
for sizing and endpoints, seed videos, then run the search-profile readiness checks.
Edge target: route through
```
references/edge.md
```
, then use the same
```
generated.env
```
→ dry-run → normalize → deploy flow.

Limitations

This skill deploys compose-based VSS profiles only; standalone microservice deployment belongs to the matching
```
vss-deploy-*
```
skill.
Hardware sizing, model placement, and profile-specific readiness are owned by profile references; do not infer them from memory.
Privileged host remediation requires user approval when passwordless sudo is unavailable.

Troubleshooting

Start with

references/agent-failure-modes.md

for cross-profile failures such as NIM cold-start timeouts, OOM, remote endpoint 5xx responses, missing

NGC_CLI_API_KEY

HF_TOKEN

, unexpanded values in

resolved.yml

etc.

vss-deploy-profile

NPX Install

Tags

SKILL.md Content

VSS Deploy

Purpose

Available Scripts

Profile Routing

Instructions

Prerequisites

Pre-flight check

Model Selection

Deployment Flow

Step 0 — Tear down any existing deployment + clear data volumes

Step 0a — Credentials gate (run before any env mutation)

Step 1 — Gather context

Step 1b — Prepare the data directory

Step 1c — Initialize
`generated.env`

Step 1d — If deploying on Brev, set
`EXTERNAL_IP`
to the secure-link domain

Step 2 — Build env_overrides

Step 3 — Apply overrides + dry-run

Step 3b — Verify resolved.yml has no unexpanded ${...} tokens

Step 3c — Strip dangling optional
`depends_on`
from resolved.yml

Step 4 — Review

Step 5 — Deploy

Step 5b — Wait until the stack is actually healthy

Tear Down

Debugging a Deployment

Quick checks (all profiles)

End-to-end video sanity check

Examples

Limitations

Troubleshooting