VSS Deploy

N'utilise pas cette compétence pour :

• Le déploiement de microservices autonomes en dehors d'un profil compose — utilise la compétence correspondante : vss-deploy-dense-captioning, vss-deploy-detection-tracking-2d, vss-deploy-detection-tracking-3d, ou vss-deploy-video-embedding.
• La synthèse ou l'interrogation d'une vidéo une fois lvs déployé — utilise vss-summarize-video.
• L'installation/configuration NGC CLI en isolation — voir references/ngc.md, ou vss-deploy-profile l'exécutera dans le cadre du contrôle des identifiants.

Scripts disponibles

Routage des profils

Associe la demande de l'utilisateur à un profil, puis charge la référence de ce profil pour le dimensionnement, les services, les recettes d'env et le débogage.

Routage matériel edge (DGX Spark, AGX/IGX Thor) : voir references/edge.md. Les trois plateformes edge exécutent le NIM par défaut du blueprint nemotron-3.5-lightning-30b-a3b sur le port 30081 en tant que vss-llm-nim ; chacune embarque sa propre paire de dimensionnement hw-*.env. Aucun élément ne réécrit plus le LLM sur edge. nvidia-nemotron-nano-9b-v2-fp8 reste accessible via un --llm explicite.

La référence de chaque profil possède sa table de dimensionnement. Ne sélectionne pas une forme de déploiement à partir de ce fichier — ouvre la référence du profil et vérifie le nombre minimum de GPU par rapport à la matrice (mode × plateforme) du matériel de l'hôte.

Instructions

Le flux de déploiement est toujours : copie overrides.env vers generated.env, applique les surcharges, exécute un dry-run de compose vers resolved.yml avec les deux couches d'env, vérifie, normalise, déploie avec les mêmes couches d'env, puis attend la disponibilité.

# 1. cp dev-profile-<profile>/overrides.env dev-profile-<profile>/generated.env  (copie propre)
# 2. Applique les surcharges d'env à generated.env  (les fichiers .env et overrides.env restent intouchés)
# 3. docker compose --env-file .env --env-file generated.env config > resolved.yml  (dry-run)
# 4. Examine resolved.yml
# 5. docker compose --env-file .env --env-file generated.env -f resolved.yml up -d

.env est la couche stable par défaut en lecture seule soumise au contrôle de version. overrides.env est la couche de surcharge du profil en lecture seule soumise au contrôle de version pour les valeurs que les scripts de déploiement peuvent modifier par hôte/profil. generated.env est la copie de travail par déploiement créée à partir de overrides.env. L'étape 1c couvre entièrement cela.

Conditions préalables

1. Chemin du repo — détecte automatiquement video-search-and-summarization/ avant de demander à l'utilisateur. Utilise le chemin détecté comme $REPO pour toutes les commandes suivantes.
2. Contrôles des identifiants — voir references/credentials.md : NGC_CLI_API_KEY pour les tirages NIM locaux/local_shared, NVIDIA_API_KEY pour les endpoints NIM distants, et HF_TOKEN pour les recettes edge utilisant des modèles HF avec accès restreint.
3. Conditions préalables du système (pilote GPU, Docker, NVIDIA Container Toolkit, sysctls du noyau, et — si ufw est actif — l'autorisation du pare-feu Docker-bridge→hôte afin que les NIMs bridge puissent récupérer les clips du VST en mode hôte) — contrôles complets dans references/prerequisites.md. La matrice matériel/pilote canonique est la page des conditions préalables VSS.

L'extrait de détection automatique (racine git, puis une sonde de chemin courant filtré sur deploy/docker/compose.yml + dev-profile.sh + skills/deployment/vss-deploy-profile) se trouve dans references/prerequisites.md. Exporte le $REPO résolu ; si la détection échoue, demande à l'utilisateur le chemin du checkout.

Vérification avant le décollage

À exécuter avant chaque déploiement. La liste de contrôle système complète et les étapes de correction se trouvent dans references/prerequisites.md. Pour DGX Spark / IGX Thor / AGX Thor, exécute également la vérification du nettoyeur de cache dans references/edge.md.

Détecte d'abord le mode sudo. Plusieurs remédiation de pré-vol et l'installeur du nettoyeur de cache edge appellent sudo. Si l'hôte nécessite un mot de passe sudo, ces étapes ne fonctionneront pas en silence sous sudo -n et laisseront le déploiement dans un état partiellement préparé.

if sudo -n true 2>/dev/null; then
  echo "sudo sans mot de passe — la pré-vol installera automatiquement les pièces manquantes"
else
  echo "sudo nécessite un mot de passe — la pré-vol n'installera PAS automatiquement ; transmets les commandes à l'utilisateur"
fi

Quand sudo a besoin d'un mot de passe, la compétence ne doit pas exécuter elle-même les installateurs privilégiés. Présente le bloc de commande copiable-collable de references/prerequisites.md à l'utilisateur avec un handoff « exécute cela une fois et confirme », puis reprends après la réponse de l'utilisateur.

Test de fumée minimum (doit réussir) :

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"

Si le test de fumée échoue, ne procède pas ; ouvre references/prerequisites.md pour l'arborescence de correction.

Sélection du modèle

• $LLM_REMOTE_URL / $VLM_REMOTE_URL si l'utilisateur demande distant
• $NGC_CLI_API_KEY (NIMs locaux) ou $NVIDIA_API_KEY (distant)

Portail d'intention d'endpoint. N'infère pas le placement distant à partir de variables d'env orphelines (LLM_ENDPOINT_URL, VLM_ENDPOINT_URL, LLM_BASE_URL, VLM_BASE_URL peuvent être des reliquats). Utilise LLM/VLM distant uniquement quand (1) l'utilisateur a demandé / fourni un endpoint distant, (2) le dimensionnement local ne peut pas contenir les modèles sélectionnés et l'utilisateur accepte, ou (3) une recette edge a besoin d'un service local autonome que VSS traite comme remote (p. ex. un endpoint compatible OpenAI externe par edge.md sur localhost:30081). Si une variable d'endpoint est définie mais l'utilisateur n'a pas demandé distant, la surface à l'étape 1 et demande — ne déploie jamais distant en silence parce qu'une variable existe.

Si aucune combinaison sur cet hôte ne satisfait les exigences de dimensionnement du profil, arrête et rapporte le blocage — ne sélectionne pas silencieusement une autre forme.

Le mode partagé edge est spécifique à la plateforme. Les recettes complètes sont dans references/edge.md.

Flux de déploiement

Toujours suit cette séquence. N'ignore jamais le dry-run.

Étape 0 — Démonte tout déploiement existant + efface les volumes de données obsolètes

Si un déploiement existe déjà, démonte-le ET efface les volumes de données obsolètes avant le redéploiement.

La procédure complète se trouve dans references/teardown.md.

Étape 0a — Contrôle des identifiants (exécute avant toute mutation d'env)

Valide chaque identifiant et endpoint distant sélectionné dont le profil choisi a besoin avant l'étape 1c qui copie overrides.env vers generated.env. Un 401 ici c'est un échec en 30 secondes ; le même 401 dans un démarrage à froid NIM c'est un échec en 10–20 min. Exécute le flux de découverte et de sonde dans references/credentials.md, incluant scripts/probe_remote_models.sh pour tout endpoint LLM/VLM que tu prévois d'écrire dans generated.env. Mappe le résultat au mode choisi : les identifiants/endpoints requis manquants ou invalides sont des blocages, les identifiants optionnels ne le sont pas.

Étape 1 — Rassemble le contexte

Avant de construire les surcharges d'env, confirme :

Avant docker compose up, vérifie que EXTERNAL_IP, HAPROXY_HOST_PORT, VSS_PUBLIC_HOST et VSS_PUBLIC_PORT sont remplis avec des valeurs accessibles au navigateur. Sinon la stack peut sembler saine tandis que les liens UI/API/VST retournent 404 ou boucle via Cloudflare Access.

Étape 1b — Prépare le répertoire de données

La disposition (chemins d'actifs, propriété, points de montage, sous-répertoires spécifiques au profil) est documentée dans references/data-directory.md. Lis ce fichier avant de déployer pour la première fois sur un hôte ou lors du changement de profils.

Étape 1c — Initialise generated.env

La copie de travail par déploiement de la compétence. Commencce toujours par une copie propre de overrides.env, ne mute jamais .env ou overrides.env.

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

cp "$ENV_POST" "$ENV_GEN"

Toutes les écritures suivantes (Brev EXTERNAL_IP, le dict env_overrides de l'étape 2) vont vers $ENV_GEN. $ENV_SRC et $ENV_POST sont en lecture seule à partir de là, et Compose doit recevoir $ENV_SRC avant $ENV_GEN.

Étape 1d — Brev uniquement : détecte d'abord, puis définis EXTERNAL_IP sur le domaine du lien sécurisé

Détecte Brev avant tout — une instance provisionnée par Brev définit BREV_ENV_ID dans /etc/environment ; rien d'autre ne le fait :

grep -qE '^BREV_ENV_ID=' /etc/environment && echo "sur Brev" || echo "pas sur Brev"

• pas sur Brev → ignore le reste de cette étape et ne lis pas references/brev.md ; conserve le EXTERNAL_IP basé sur ${HOST_IP} normal.
• sur Brev → applique les surcharges de lien sécurisé Brev de references/brev.md § Setup flow vers generated.env (PAS .env). Celles-ci définissent EXTERNAL_IP / VSS_PUBLIC_HOST au domaine du lien sécurisé et VSS_PUBLIC_HTTP_PROTOCOL=https / VSS_PUBLIC_WS_PROTOCOL=wss / VSS_PUBLIC_PORT=443 — définir EXTERNAL_IP seul laisse les liens UI/API/WS http://…:7777 que le navigateur bloque comme contenu mixte.

Étape 2 — Construis env_overrides

Produis un dict env_overrides à partir de la demande de l'utilisateur et du contexte rassemblé : choisis explicitement distant/local LLM/VLM, définis les identifiants, pointe vers les endpoints, définis les drapeaux spécifiques à la plateforme. Ne laisse pas les variables d'env shell existantes choisir silencieusement le placement ; écris le LLM_MODE / VLM_MODE sélectionné et les champs d'endpoint/modèle correspondants dans generated.env. Le mappage complet (chaque clé de surcharge, quand elle s'applique, les défauts, les différences spécifiques au profil) se trouve dans references/env-overrides.md. Chaque référence de profil a des exemples travaillés pour les scénarios courants de ce profil.

Étape 3 — Applique les surcharges + dry-run

Fichiers d'env de travail : <repo>/deploy/docker/developer-profiles/dev-profile-<profile>/.env plus <repo>/deploy/docker/developer-profiles/dev-profile-<profile>/generated.env (créé à l'étape 1c à partir de overrides.env).

Rappel (voir Étape 1c) : applique toutes les surcharges (dict Étape 2 + Brev EXTERNAL_IP) vers generated.env ; Compose obtient .env d'abord et generated.env en second, et les vérificateurs post-déploiement lisent generated.env pour les valeurs de surcharge réellement déployées.

# (L'étape 1c a déjà exécuté : cp $ENV_POST $ENV_GEN)

# Applique le dict env_overrides de l'étape 2 à generated.env
# (lit les lignes, met à jour les clés correspondantes, ajoute les nouvelles clés, écrit)
# Exemple :
#   sed -i "s|^LLM_MODE=.*|LLM_MODE=remote|" "$ENV_GEN"
#   sed -i "s|^LLM_BASE_URL=.*|LLM_BASE_URL=http://localhost:30081|" "$ENV_GEN"

# Résout compose
cd $REPO/deploy/docker
docker compose --env-file $ENV_SRC --env-file $ENV_GEN config > resolved.yml

Le YAML résolu est sauvegardé vers <repo>/deploy/docker/resolved.yml.

Étape 3b — Vérifie que resolved.yml n'a aucun token ${...} non expansé

Les tokens ${VAR} non expansés dans resolved.yml signifient que compose n'a pas vu ces valeurs d'env. La procédure de diagnostic et les coupables courants se trouvent dans references/troubleshooting.md.

Étape 3c — Vérifie l'accès aux artefacts NGC sélectionnés

Après l'existence de resolved.yml et avant le démarrage de Compose, suis references/credentials.md § Artifact Entitlement Probes. Vérifie chaque image de conteneur sélectionnée, chemin de ressource/modèle NGC et artefact organisé par profil. L'authentification seule ne prouve pas le droit d'accès au référentiel. Tout échec d'accès est un blocage ; ne démarre pas Compose.

Étape 3d — Supprime les depends_on optionnels orphelins de resolved.yml

DOIT s'exécuter après l'étape 3, avant l'étape 5. Sauter cela abandonne le déploiement :

Normalise - supprime les dépendances optionnelles pour les services filtrés hors de resolved.yml

# Depuis la racine du repo
uv run skills/deployment/vss-deploy-profile/scripts/normalize_resolved_yml.py "$REPO/deploy/docker/resolved.yml"

Si uv n'est pas sur l'hôte, installe-le une fois avec curl -LsSf https://astral.sh/uv/install.sh | sh (aucune racine nécessaire). Révalide avant up -d :

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

Si la validation échoue toujours après l'exécution du normaliseur, capture l'erreur et inspecte — c'est un bug différent (une dépendance qui n'est pas optionnelle, ou une autre violation de schéma), pas le cas des depends_on orphelins.

Étape 4 — Examine

Affiche à l'utilisateur un résumé de ce qui sera déployé :

• Nom du profil et matériel
• Modèles LLM/VLM et mode (local/distant/local_shared)
• Services qui démarreront
• Attribution des dispositifs GPU
• Points d'extrémité clés (port UI, port agent)

Demande : « Ça a l'air bon — déployer maintenant ? » et attends la confirmation avant l'étape 5.

Exception — mode autonome. Si la demande de l'utilisateur demande déjà l'exécution en mode autonome (p. ex. « deploy X autonomously », « run without confirmation », « non-interactive »), ignore l'invite de confirmation et procède directement à l'étape 5. Ce chemin existe pour que les évaluations automatisées / les invocations CI ne restent pas bloquées en attente d'une réponse humaine qu'elles n'auront jamais. Dans tous les autres cas, un humain doit approuver.

Étape 5 — Déploie

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

Les deux arguments --env-file sont obligatoires et ordonnés. Sans la même paire .env + generated.env utilisée à l'étape 3, COMPOSE_PROFILES peut ne pas être défini ou incomplet et up -d peut quitter 0 avec zéro services sélectionnés.

Évite les --force-recreate larges sur les simples tentatives — cela détruit les conteneurs NIM chauds (3–5 min torch.compile + CUDA-graph capture supplémentaires chacun). Corrige la cause racine (généralement les perms ou une typo d'env) et réexécute simplement up -d ; utilise --force-recreate --no-deps <service...> ciblé uniquement quand une référence de profil le documente comme chemin de récupération.

docker compose up -d crée uniquement les conteneurs ; il n'attend pas que les services internes terminent le réchauffement. Ne déclare jamais le déploiement réussi tant que les portails de disponibilité n'ont pas passé.

Étape 5b — Attends jusqu'à ce que la stack soit vraiment saine

Portail 0 — le nombre de conteneurs doit être > 0. Refuse de procéder au-delà de up -d jusqu'à ce que le nombre démarré (docker compose -f resolved.yml ps -q | wc -l) soit non nul et ≥ le nombre attendu (config --services | wc -l) ; un nombre zéro/court signifie presque toujours un --env-file manquant à l'étape 5. Le portail exact plus la procédure de disponibilité complète se trouvent dans references/readiness.md.

Les déploiements à froid peuvent prendre 10–20 min, et chaque référence de profil liste les endpoints requis. Ne déclare jamais le déploiement terminé après up -d ; uniquement après que chaque endpoint documenté réussisse.

Démontage

Pour démonter un déploiement — réclamation d'hôte complet ou redéploiement préservant le cache / commutation de profil — suis references/teardown.md. Démonte toujours par le projet mdx avec -v --remove-orphans ; un simple docker compose down laisse les volumes et réseaux derrière.

Débogage d'un déploiement

Utilise ce flux de travail quand l'utilisateur demande à « déboguer le déploiement », « vérifier que c'est fonctionnant », « pourquoi l'agent ne répond pas », ou similaire. L'objectif est de confirmer le chemin complet d'ingestion vidéo-à-réponse-agent, pas seulement que les conteneurs soient « Up ».

Chaque référence de profil a une section Debugging listant les commandes exactes et le tableau de mode d'échec pour ce profil.

Contrôles rapides (tous les profils)

# 1. Tous les conteneurs attendus Up
docker ps --format 'table {{.Names}}\t{{.Status}}'

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

Les sondes LLM/VLM NIM — incluant la gestion *_MODE=remote qui ignore localhost:3008x (où un refus de connexion est attendu) et sonde le /v1/models d'*_BASE_URL sélectionné via scripts/probe_remote_models.sh — sont dans references/troubleshooting.md.

Limitations

• Cette compétence déploie uniquement les profils VSS basés sur compose ; le déploiement de microservices autonomes appartient à la compétence vss-deploy-* correspondante.
• Le dimensionnement matériel, le placement des modèles et la disponibilité spécifique au profil sont possédés par les références de profil ; ne les infère pas de la mémoire.
• La correction host privilégiée nécessite l'approbation de l'utilisateur quand le sudo sans mot de passe n'est pas disponible.

Dépannage

La référence rapide d'erreur courante, le tableau complet symptôme → cause → correction, le diagnostic ${...} non expansé, et les sondes d'endpoint NIM sont consolidés dans references/troubleshooting.md — commence là pour tout échec de déploiement, runtime ou sonde, puis continue dans la section Debugging de la référence per-profil correspondante.