<!-- 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 APPROOT, 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 $VSSCREDENTIALS_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/.

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

1. Reuse a checkout a previous bootstrap already placed in

${XDGCACHEHOME:-$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 APPROOT. To pull from a fork/branch or reuse a specific checkout dir, override VSSREPOURL, VSSREPOBRANCH, or VSSCLONE_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:

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

1. 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](./vss.config). - Credentials are generated at runtime outside the checkout, at ${XDGCONFIGHOME:-$HOME/.config}/vss/vss.credentials, by [scripts/gen-secrets.sh](./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:

``bash export VSSCREDENTIALSFILE="${XDGCONFIGHOME:-$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 "$VSSCREDENTIALSFILE" ``

Common to every mode: MINIOROOTUSER, MINIOROOTPASSWORD, POSTGRESUSER, POSTGRESPASSWORD, RABBITMQUSER, RABBITMQPASSWORD. Mode-specific model vars (VLMMODELNAME, ENABLEDWHISPERMODELS, ODMODELNAME for summary; MULTIMODALEMBEDDINGMODEL for search/dual; TEXTEMBEDDINGMODEL for unified) ship with defaults in vss.config - see [references/env-vars.md](./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.

1. Dry-run first when unsure - append config to render the resolved

Compose configuration without starting containers, then review before the real deploy:

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

1. 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 bash -c ' source setup.sh --stop # clear any running stack first export VSSCREDENTIALSFILE="${XDGCONFIGHOME:-$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 "$VSSCREDENTIALSFILE" source setup.sh --summary # the chosen mode ' ``

Run this in the background (runinbackground: 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 MODELDOWNLOADJOBTIMEOUT per job (default 5400 seconds), writes failed service logs to ovmodels/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: > > ``bash > APPHOSTPORT=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, APPHOSTPORT, registry and > device settings) - not the mode-derived ones such as VSINDEXNAME or > EMBEDDINGMODELNAME. 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, APPHOSTPORT=18080 source setup.sh --summary-and-search in the deployment subshell), then give the user the interactive APPHOSTPORT=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.

1. Wait for health, then print URLs. Keep the probe in the invoking

shell so this skill does not ship an executable network helper:

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

Mode aliases and config-only inspection

setup.sh normalizes --summary --search and --search --summary to --dual; --summary-and-search, --search-and-summary, and --all to --unified; config to --dual config; config --summary to --summary config; and --down to --stop. Use config mode to verify the resolved Compose without starting containers:

source setup.sh --summary config
source setup.sh --search config
source setup.sh --summary --search config
source setup.sh --summary-and-search config

Choose OVMS, vLLM, CPU, or GPU

Default summarization backend is OVMS (ovms-service, profile ovms) from docker/compose.summary.yaml.

source setup.sh --summary                                                # OVMS CPU default
VLM_TARGET_DEVICE=GPU source setup.sh --summary                          # OVMS GPU for VLM
LLM_TARGET_DEVICE=GPU OVMS_LLM_MODEL_NAME=<llm> source setup.sh --summary # OVMS GPU for LLM
ENABLE_VLLM=true source setup.sh --summary                               # vLLM CPU backend
ENABLE_VLLM_GPU=true source setup.sh --summary                           # experimental vLLM XPU/GPU backend
ENABLE_EMBEDDING_GPU=true source setup.sh --search                       # GPU for search embeddings

For vLLM, setup.sh adds docker/compose.vllm.yaml, starts vllm-cpu-service (profile vllm) on host port 8200, and uses VLMMODELNAME for both captioning and final summary. Experimental ENABLEVLLMGPU=true instead adds docker/compose.vllm.xpu.yaml, selects profile vllm-xpu, and disables OVMS. For OVMS GPU, setup.sh adds docker/compose.gpuovms.yaml and switches ovms-service to openvino/modelserver:2026.1-gpu.

The skill's fresh bash -c deployment flow prevents derived OVMS storage names from leaking between runs. If switching from OVMS to vLLM manually in the same interactive shell, first run unset VLMSTORAGEMODELNAME LLMSTORAGEMODELNAME; otherwise Compose can reuse an OVMS storage alias that vLLM does not serve.

Lifecycle: bring down or reset

Run these yourself via bash -c 'source setup.sh …'. --stop, --down, --clean-data, and config-only inspection (<mode> config) skip the required environment validation entirely, so they are mode-agnostic and need no config or credentials sourced first.

source setup.sh --stop       # stop/remove containers across all VSS overlays/profiles
source setup.sh --down       # alias for --stop
source setup.sh --clean-data # also removes the VSS application data volumes
source setup.sh --help       # full help

--clean-data removes the user-data volumes only: dockerminiodata, dockerpgdata, dockervdms-db, dockermilvus-db, dockermilvus-etcd, dockeraudioanalyzerdata, and dockerdata-prep (volumes absent in the current mode are skipped). The model-cache volumes - dockerdataprep-yolox-models, dockerov-models, dockervllmmodelcache - and the host-backed ov_models/ directory are deliberately preserved, so a --clean-data never forces a costly model re-download.

Default ports & URLs

HOSTIP is auto-detected by setup.sh; APPHOST_PORT defaults to 12345.

Troubleshooting ("why won't vss come up")

1. ERROR: <VAR> is not set → missing shell env var; re-source vss.config

plus $VSSCREDENTIALSFILE (step 2).

1. Invalid VECTORDBBACKEND → set VECTORDBBACKEND to vdms

or milvus.

1. Health never goes green → docker compose ps for crashed containers, then

docker compose logs <service>. The heavy ones are model servers (ovms, vlm-ov/vllm, embedding).

1. Wrong/partial stack already running → source setup.sh --stop then redeploy.
2. Setup fails before Compose starts → inspect the reported

ovmodels/model-download-*.log; if loopback port 8640 is occupied, set MODELDOWNLOADHOSTPORT to a free port and rerun.

For anything past these basics - model-server crashes, OVMS token/cache/GPU errors, host model-cache or model-download permission failures, search returning no results, NPU/OpenGL issues - hand off to the installed vss-troubleshoot skill by name and the canonical guide at docs/user-guide/troubleshooting.md.

Final answer audit trail

Tool arguments may not be visible to the user or evaluator. The final answer must therefore report the bootstrap result: resolved APP_ROOT, the change to that directory, and whether an existing checkout was reused without cloning. Also state that a total bootstrap miss falls back to a shallow (--depth 1), single-branch, sparse checkout of only the VSS app from main.

Name every requested setup.sh operation exactly, including overrides and mode flags, and distinguish commands that completed from commands blocked by the host. For a blocked deployment, still provide the exact sourced deploy command, health endpoint, and resulting URL. For --clean-data, say that it performs the stop/removal itself, list the affected user-data volumes, and explicitly state that model-cache volumes and the host-backed ov_models/ directory are preserved.

References

• Exact mode-to-overlay/profile/service/URL mapping:

[references/modes-and-overlays.md](./references/modes-and-overlays.md).

• Required and optional environment variables:

[references/env-vars.md](./references/env-vars.md).