Vss Deploy

<!--
SPDX-FileCopyrightText: (C) 2026 Intel Corporation
SPDX-License-Identifier: Apache-2.0
-->

VSS Deploy

Deploy, switch, inspect, and tear down VSS with setup.sh. Use this skill only for sample-applications/video-search-and-summarization. Ground every answer in the repository files - especially setup.sh and docker/compose.*.yaml - and do not invent flags, services, ports, or variables. Run the commands yourself and relay the output; do not hand the deploy command to the user (the lone exception is --setenv, see below).

Answer contract when the host is not reachable

The user may be planning ahead, or Docker / the VSS source may be unavailable here. In that case do not stall and do not invent output. Answer with the exact command sequence instead: the bootstrap step, the config/secrets step, the setup.sh invocation with its flags, the health wait, and the resulting URLs - plus which command the user must run themselves and why. State plainly that the commands were not executed. Never end the answer by asking whether to run them.

Mandatory bootstrap and credential contract

Every deployment answer must run or, after a host blocker, show and report this exact setup shape:

SKILL_DIR=".github/skills/vss-deploy"
APP_ROOT="$(bash "$SKILL_DIR/scripts/vss-bootstrap.sh")"
cd "$APP_ROOT"
export VSS_CREDENTIALS_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/vss/vss.credentials"
./.github/skills/vss-deploy/scripts/gen-secrets.sh
source .github/skills/vss-deploy/vss.config
source "$VSS_CREDENTIALS_FILE"

Report the resolved APP_ROOT, whether it was reused without cloning, and the bootstrap's no-hit fallback (shallow --depth 1, single-branch, sparse checkout of only the VSS app from main). The canonical files are vss.config and the external $VSS_CREDENTIALS_FILE; do not substitute stale filenames such as vss.config.env, vss.secrets.env, or an in-checkout credentials file.

Before any real deploy, config render, stop, or model-download path, run a bounded Docker host preflight such as docker info >/dev/null 2>&1. If it fails, stop immediately: do not invoke setup.sh, do not wait for model download, and do not retry a missing daemon. Report the observed host blocker and provide the exact deferred sourced command sequence required by the answer contract.

Environment setup (run first)

This skill drives the Video Search & Summarization app through its real source files, so the VSS application must be present and you must run commands from its app root. Do this before anything else, and it works whether or not the VSS source is already in your workspace.

Run the bundled bootstrap. It resolves the app root in this order and prints it as the only line on stdout:

1. Walk up from the current directory looking for a VSS app root - a directory carrying all three markers setup.sh, docker/, and pipeline-manager/.
2. Ask git for the enclosing repository (git rev-parse --show-toplevel) and check whether it holds sample-applications/video-search-and-summarization, or is itself a VSS app root. This is what makes your own clone - or a fork - work unchanged.
3. Reuse a checkout a previous bootstrap already placed in ${XDG_CACHE_HOME:-$HOME/.cache}/vss-src/edge-ai-libraries.

If any of those hit, that checkout is reused and NO clone is performed. Only when all three miss does it clone - and then only a shallow (--depth 1), single-branch, sparse checkout of just sample-applications/video-search-and-summarization from main:

# SKILL_DIR is THIS skill's own directory (shown to you when the skill loads);
# in-repo it is .github/skills/vss-deploy. Works the same if the skill is installed standalone.
SKILL_DIR=".github/skills/vss-deploy"
APP_ROOT="$(bash "$SKILL_DIR/scripts/vss-bootstrap.sh")"
cd "$APP_ROOT"

Every command below assumes the working directory is this APP_ROOT. To pull from a fork/branch or reuse a specific checkout dir, override VSS_REPO_URL, VSS_REPO_BRANCH, or VSS_CLONE_DIR before running it. The bootstrap refuses to overwrite an existing non-VSS clone destination.

Mode routing

If the user is ambiguous, ask which mode; do not default silently.

Quick deployment flow

1. Work from the app root:

   cd sample-applications/video-search-and-summarization

2. Provide config + credentials. setup.sh reads everything from the shell environment and aborts on the first missing required var. The repository now provides .env.example as a general application template, but this skill keeps config and generated credentials split so credentials never enter a committed file:

   • Non-secret config - models, ports, tuning - lives in committed vss.config.
   • Credentials are generated at runtime outside the checkout, at ${XDG_CONFIG_HOME:-$HOME/.config}/vss/vss.credentials, by scripts/gen-secrets.sh (strong random values, created once and reused so data volumes stay valid).

   Generate credentials once, then source both files in the same shell:

   export VSS_CREDENTIALS_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/vss/vss.credentials"
   ./.github/skills/vss-deploy/scripts/gen-secrets.sh     # creates it if absent
   source .github/skills/vss-deploy/vss.config
   source "$VSS_CREDENTIALS_FILE"

   Common to every mode: MINIO_ROOT_USER, MINIO_ROOT_PASSWORD, POSTGRES_USER, POSTGRES_PASSWORD, RABBITMQ_USER, RABBITMQ_PASSWORD. Mode-specific model vars (VLM_MODEL_NAME, ENABLED_WHISPER_MODELS, OD_MODEL_NAME for summary; MULTIMODAL_EMBEDDING_MODEL for search/dual; TEXT_EMBEDDING_MODEL for unified) ship with defaults in vss.config - see references/env-vars.md for the full table. To inject your own credentials (vault/CI) instead of random ones, export them before running gen-secrets.sh - it reuses any credential already set.

3. Dry-run first when unsure - append config to render the resolved Compose configuration without starting containers, then review before the real deploy:

   source setup.sh --summary config     # or --search / --summary --search / --summary-and-search

4. Deploy - run it yourself. setup.sh must be sourced (it uses return and exports env while building the Compose command), but it does not need the user's interactive shell: deploy uses docker compose up -d (detached), so containers keep running after the subshell exits. First bring any prior stack down so a stale/wrong-mode deployment can't collide, then deploy - run the whole chain in one bash -c invocation:

   bash -c '
     source setup.sh --stop                                  # clear any running stack first
     export VSS_CREDENTIALS_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/vss/vss.credentials"
     ./.github/skills/vss-deploy/scripts/gen-secrets.sh       # creates it if absent
     source .github/skills/vss-deploy/vss.config
     source "$VSS_CREDENTIALS_FILE"
     source setup.sh --summary                                # the chosen mode
   '

   Run this in the background (run_in_background: true) or with a long timeout. Before Compose starts, setup.sh launches a transient vss-model-download container on loopback port 8640 when the selected OD artifact or an OVMS VLM/split LLM artifact is missing. It submits REST jobs, waits up to MODEL_DOWNLOAD_JOB_TIMEOUT per job (default 5400 seconds), writes failed service logs to ov_models/model-download-*.log, removes the transient container, and only then runs docker compose up -d.

   Only exception: --setenv exists solely to leave env vars in the user's interactive shell for later manual use - a subshell can't do that, so for that verb only, give the user the !-prefixed command to run themselves:

   APP_HOST_PORT=18080 source setup.sh --setenv      # port override optional

   --setenv takes no mode flag. setup.sh rejects any two-argument form other than <mode> config / config <mode>, so --setenv --summary-and-search fails with "Invalid argument combination". It returns before the mode dispatch, so it exports the mode-agnostic vars (credentials, APP_HOST_PORT, registry and device settings) - not the mode-derived ones such as VS_INDEX_NAME or EMBEDDING_MODEL_NAME. Export those by hand if the user needs full parity for manual docker compose calls.

   If the user asks for both a deployment and persistent variables for later manual Compose commands, satisfy both parts separately: first run the real deployment flow with the selected mode and overrides (for example, APP_HOST_PORT=18080 source setup.sh --summary-and-search in the deployment subshell), then give the user the interactive APP_HOST_PORT=18080 source setup.sh --setenv command plus any required mode-derived exports. --setenv prepares their future shell; it is not a substitute for the requested deployment.

5. Wait for health, then print URLs. Keep the probe in the invoking shell so this skill does not ship an executable network helper:

   VSS_BASE="http://${HOST_IP:-localhost}:${APP_HOST_PORT:-12345}"
   deadline=$(( $(date +%s) + 300 ))
   until curl -sf --max-time 5 "$VSS_BASE/manager/health" >/dev/null; do
     if [ "$(date +%s)" -ge "$deadline" ]; then
       echo "VSS health check timed out: $VSS_BASE/manager/health" >&2
       docker compose ps
       exit 1
     fi
     sleep 5
   done
   echo "UI: $VSS_BASE/"
   echo "Pipeline Manager: $VSS_BASE/manager/docs"