Compétence : Lancer les Conteneurs de Version AutoMagicCalib

Quand Utiliser Cette Compétence

Activez cette compétence quand l'utilisateur veut déployer la stack AutoMagicCalib. Invites typiques :

• « deploy auto calibration »
• « launch auto calibration » / « launch AMC »
• « start MS+UI » / « bring up the microservice and UI »
• « set up auto-magic-calib »

Prérequis : clé API NGC (la compétence la demande). Pour une première installation sur une machine vierge, cette compétence résout ou clone aussi le repo auto-magic-calib après confirmation explicite de l'utilisateur.

Vue d'ensemble

Lancez le microservice AutoMagicCalib (MS) et l'UI à partir d'images de version précompilées via Docker Compose. Utilisez ceci pour les déploiements en production ou quand vous voulez exécuter la stack complète (backend + web UI) sans compiler les images localement.

Prérequis

• Docker et Docker Compose installés
• Runtime NVIDIA Docker configuré (pour le support GPU)
• Repo auto-magic-calib sur disque — l'étape 0b résout automatiquement un checkout existant via git rev-parse --show-toplevel, ou propose de cloner https://github.com/NVIDIA-AI-IOT/auto-magic-calib dans ~/auto-magic-calib si aucun n'est trouvé
• Compte NGC avec accès au registre de conteneurs NVIDIA
• Docker doit être exécutable sans sudo — vérifiez avec docker ps. S'il échoue, demandez à l'utilisateur de suivre les étapes post-installation : https://docs.docker.com/engine/install/linux-postinstall/

Si docker ps échoue avec « permission denied », demandez à l'utilisateur d'exécuter :

sudo usermod -aG docker $USER
newgrp docker   # applique le changement de groupe dans le shell actuel sans déconnexion

Ensuite vérifiez avec docker ps avant de continuer.

Instructions

Étape 0 : Vérifier que Docker s'Exécute Sans sudo

docker ps

• Si cela réussit → continuez.
• Si cela échoue avec « permission denied » → l'utilisateur n'est pas dans le groupe docker. Demandez à l'utilisateur d'exécuter :

  sudo usermod -aG docker $USER && newgrp docker

  Puis demandez à l'utilisateur de confirmer que docker ps fonctionne avant de continuer.

Note agent : Si docker ps ne peut pas être exécuté depuis le sandbox agent, demandez à l'utilisateur de confirmer que cela fonctionne (par ex. « Pouvez-vous confirmer que docker ps s'exécute sans sudo ? ») avant de continuer.

Étape 0b : Résoudre le Checkout du Repo

La compétence a besoin de compose/, assets/sdg_08_2_sample_data_010926.zip et d'un point de montage models/ — tous situés dans le repo auto-magic-calib. Si vous êtes déjà dans un checkout, la compétence l'utilise. Sinon, elle demande une confirmation explicite de l'utilisateur via le mécanisme de question de l'hôte ; si aucun n'est disponible, demandez en chat et attendez avant de cloner dans ~/auto-magic-calib.

REPO_URL="https://github.com/NVIDIA-AI-IOT/auto-magic-calib.git"
DEFAULT_CLONE_DIR="$HOME/auto-magic-calib"

# 1. Déjà dans un checkout utilisable ?
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
if [ -n "$REPO_ROOT" ] && [ -f "$REPO_ROOT/compose/compose.yml" ] && [ -d "$REPO_ROOT/assets" ]; then
  echo "✓ Using existing checkout: $REPO_ROOT"

# 2. Répertoire de clone par défaut déjà rempli d'une exécution antérieure ?
elif [ -d "$DEFAULT_CLONE_DIR/.git" ] && [ -f "$DEFAULT_CLONE_DIR/compose/compose.yml" ]; then
  REPO_ROOT="$DEFAULT_CLONE_DIR"
  echo "✓ Found existing clone at $REPO_ROOT"

# 3. Rien sur disque — ARRÊTEZ et demandez la confirmation de l'utilisateur via
#    le mécanisme de question de l'hôte ; si aucun n'est disponible, demandez en chat et attendez.
#    Ne clonez PAS silencieusement à partir de ce bloc.
else
  echo "No auto-magic-calib checkout found. Ask the user for confirmation:"
  echo "  Clone $REPO_URL into $DEFAULT_CLONE_DIR? [y/N]"
  echo "On 'y' — run: git clone \"$REPO_URL\" \"$DEFAULT_CLONE_DIR\""
  exit 1
fi

cd "$REPO_ROOT"
export REPO_ROOT
echo "REPO_ROOT=$REPO_ROOT"

Note agent : ne clonez pas silencieusement. Demandez d'abord à l'utilisateur via le mécanisme de question de l'hôte ; si aucun n'est disponible, demandez en chat et attendez. Exemple : « Repo auto-magic-calib introuvable. Cloner https://github.com/NVIDIA-AI-IOT/auto-magic-calib dans ~/auto-magic-calib ? (ou fournir votre propre chemin) ». Respectez un chemin alternatif si l'utilisateur en propose un. Le clone fait quelques centaines de Mo (fichiers compose + dataset exemple + assets).

Étape 0c : Installer Python venv (Nouveaux Systèmes Uniquement)

Sur un système vierge, pip et python3-venv peuvent ne pas être disponibles. Installez-les d'abord :

# Créer un venv pour HuggingFace CLI (préféré au niveau du projet)
REPO_DIR="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
HF_VENV="${REPO_DIR}/venv"
python3 -m venv "$HF_VENV" 2>/dev/null || {
  echo "ERROR: python3-venv not available." >&2
  echo "Install it manually: sudo apt install -y python3-venv python3-pip" >&2
  exit 1
}

# Installer HuggingFace hub (nécessaire pour le téléchargement VGGT)
"$HF_VENV/bin/pip" install --upgrade pip huggingface_hub

Note : Ignorez cette étape si un venv avec hf existe déjà (vérifiez venv/bin/hf à la racine du repo ou ~/venv/amc/bin/hf).

Étape 1 : Se Connecter à NGC

Demandez à l'utilisateur sa clé API NGC via le mécanisme de question de l'hôte ; si aucun n'est disponible, demandez en chat et attendez. Ensuite exécutez :

echo "<NGC_API_KEY>" | docker login nvcr.io --username '$oauthtoken' --password-stdin
echo "✓ NGC authentication complete"

Étape 2 : Télécharger le Modèle VGGT (s'il n'est pas déjà Présent)

export REPO_ROOT=$(git rev-parse --show-toplevel)
cd "$REPO_ROOT"

if [ -f "models/vggt/vggt_1B_commercial.pt" ]; then
  echo "✓ VGGT model already present"
else
  echo "✗ VGGT model not found"
  echo "Options:"
  echo "  1. Continue without VGGT (AMC only - sufficient for most use cases)"
  echo "  2. Download VGGT model (~4.7GB, requires HuggingFace account)"
fi

Pour télécharger VGGT (demandez à l'utilisateur un token HuggingFace via le mécanisme de question de l'hôte ; si aucun n'est disponible, demandez en chat et attendez) :

Étape 2a : Accepter la Licence du Modèle (obligatoire, une seule fois) :

1. Visitez : https://huggingface.co/facebook/VGGT-1B-Commercial
2. Connectez-vous à votre compte HuggingFace
3. Cliquez « Agree and access repository » pour accepter les conditions de licence

Étape 2b : Obtenir un Token HuggingFace :

1. Visitez : https://huggingface.co/settings/tokens
2. Créez un nouveau token avec accès « Read » (commence par hf_...)
3. Demandez le token à l'utilisateur via le mécanisme de question de l'hôte ; si aucun n'est disponible, demandez en chat et attendez. Ne lui demandez PAS d'exécuter une commande

Étape 2c : Télécharger (passez le token via la variable d'env HF_TOKEN — garde le secret hors argv de hf / ps aux ; pas de connexion interactive nécessaire) :

REPO_DIR="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
cd "$REPO_DIR"

# Trouver le binaire HuggingFace CLI (nommé 'hf', pas 'huggingface-cli')
HF_BIN="$(find "$REPO_DIR/venv" ~/venv/amc -name hf -type f 2>/dev/null | head -1)"
{ [ -z "$HF_BIN" ] || [ ! -x "$HF_BIN" ]; } && { echo "ERROR: hf binary not found or not executable; install the hf CLI (Step 0c) or set HF_BIN" >&2; exit 1; }

# Ne pas utiliser --token en ligne de commande (fuite via ps/argv). Le CLI HuggingFace
# lit HF_TOKEN de l'environnement automatiquement.
HF_TOKEN="<HF_TOKEN>" "$HF_BIN" download facebook/VGGT-1B-Commercial \
  --local-dir models/vggt/

# Vérifier
ls -lh models/vggt/vggt_1B_commercial.pt
# Devrait afficher un fichier d'environ 4,7 Go

Important : Téléchargez AVANT de définir chown 1000:1000 sur le répertoire des modèles — l'utilisateur actuel a besoin de l'accès en écriture pendant le téléchargement. Définissez les permissions à l'étape 4 après la fin du téléchargement.

Étape 3 : Configurer les Variables .env

Le fichier .env à compose/.env contrôle les ports et les chemins. Mettez-le à jour avant de lancer :

cd $REPO_ROOT/compose

# Trouver un port backend disponible (8000-8009)
for port in {8000..8009}; do
  if ! lsof -Pi :$port -sTCP:LISTEN -t >/dev/null 2>&1; then
    MS_PORT=$port
    echo "Using backend port: $MS_PORT"
    break
  fi
done
[ -z "$MS_PORT" ] && { echo "ERROR: no free backend port in 8000-8009; free one or widen the range." >&2; exit 1; }

# Trouver un port UI disponible (5000-5009)
for port in {5000..5009}; do
  if ! lsof -Pi :$port -sTCP:LISTEN -t >/dev/null 2>&1; then
    UI_PORT=$port
    echo "Using UI port: $UI_PORT"
    break
  fi
done
[ -z "$UI_PORT" ] && { echo "ERROR: no free UI port in 5000-5009; free one or widen the range." >&2; exit 1; }

# Obtenir l'IP de l'hôte
HOST_IP=$(hostname -I | awk '{print $1}')
echo "Host IP: $HOST_IP"

# Mettre à jour .env — préserver les clés que l'utilisateur a déjà définies ; sauvegarder d'abord.
# .env peut contenir des identifiants, donc restreignez les permissions sur la sauvegarde et
# le fichier en direct (chmod 600). Ajoutez `compose/.env.bak.*` à .gitignore.
ENV_FILE=".env"
if [ -f "$ENV_FILE" ]; then
  BACKUP="${ENV_FILE}.bak.$(date +%s)"
  cp "$ENV_FILE" "$BACKUP"
  chmod 600 "$BACKUP"
fi
touch "$ENV_FILE"
chmod 600 "$ENV_FILE"
set_env_key() {
  local k="$1" v="$2"
  if grep -qE "^${k}=" "$ENV_FILE"; then
    sed -i "s|^${k}=.*|${k}=${v}|" "$ENV_FILE"
  else
    echo "${k}=${v}" >> "$ENV_FILE"
  fi
}
set_env_key AUTO_MAGIC_CALIB_MS_PORT "${MS_PORT}"
set_env_key AUTO_MAGIC_CALIB_UI_PORT "${UI_PORT}"
set_env_key PROJECT_DIR "../../projects"
set_env_key MODEL_DIR "../../models"
set_env_key HOST_IP "${HOST_IP}"

# Garder les sauvegardes .env horodatées hors de git.
GITIGNORE="$REPO_ROOT/.gitignore"
touch "$GITIGNORE"
grep -qxF "compose/.env.bak.*" "$GITIGNORE" || echo "compose/.env.bak.*" >> "$GITIGNORE"

echo "✓ .env updated"
cat .env

Important : HOST_IP doit être l'IP réseau de la machine (pas localhost) pour que le conteneur UI puisse atteindre le backend à partir d'un navigateur.

Optionnel : définissez VGGT_MODEL_PATH uniquement si le modèle VGGT est monté à un chemin de conteneur non-par-défaut ; la valeur par défaut est /tmp/vggt_model/vggt_1B_commercial.pt à l'intérieur du conteneur MS.

Étape 4 : Définir les Permissions des Répertoires

Les conteneurs s'exécutent en tant que UID/GID 1000. Les répertoires projects et models doivent être possédés par cet UID pour que les conteneurs puissent lire/écrire correctement :

cd "$REPO_ROOT"

# Créer le répertoire projects s'il n'existe pas
mkdir -p projects

# Définir la propriété (obligatoire pour que les conteneurs écrivent les résultats de calibrage).
# Faites ceci APRÈS la fin du téléchargement VGGT (l'utilisateur actuel a besoin de l'accès en écriture pendant le téléchargement).
# Obtenir la confirmation explicite de l'utilisateur avant d'exécuter sudo chown — cela change récursivement
# la propriété de $REPO_ROOT/projects et $REPO_ROOT/models à UID/GID 1000.
[ -d projects ] && [ -d models ] || {
  echo "ERROR: expected projects/ and models/ under $REPO_ROOT" >&2; exit 1;
}
echo "About to chown -R 1000:1000 on:"
echo "  $REPO_ROOT/projects"
echo "  $REPO_ROOT/models"
echo "(required because containers run as UID 1000). Confirm before proceeding."
sudo chown 1000:1000 -R projects
sudo chown 1000:1000 -R models

echo "✓ Permissions set"

Étape 5 : Lancer les Services

Avant de tirer, échouez rapidement si la clé NGC s'est authentifiée à l'étape 1 mais ne peut pas accéder à une image de version — sinon docker compose up s'arrête à mi-chemin avec un 401/403 après qu'un travail soit déjà en cours.

cd $REPO_ROOT/compose

# Vérification d'accès rapide : confirmer que la clé NGC peut atteindre chaque image de version
# AVANT de tirer. `docker manifest inspect` vérifie l'accès au registre sans
# télécharger de couches, et la liste d'images est lue à partir de la compose résolue afin qu'elle
# suive automatiquement la balise de version.
IMAGES=$(docker compose config --images | sort -u)
[ -z "$IMAGES" ] && { echo "ERROR: no images resolved from compose — check compose/.env and the chosen profile." >&2; exit 1; }
for img in $IMAGES; do
  echo "Checking access: $img"
  if ! docker manifest inspect "$img" >/dev/null 2>&1; then
    echo "NGC login succeeded, but this key cannot access the required image:" >&2
    echo "  $img" >&2
    echo "Provide an NGC key with access to this image's namespace, then re-run Step 1 (login) and retry." >&2
    exit 1
  fi
done

# Démarrer tous les services (images tirées automatiquement à la première exécution)
docker compose up -d

# Vérifier que les conteneurs s'exécutent
docker compose ps

Sortie attendue :

NAME                    IMAGE                                                              STATUS
auto-magic-calib-ms-1   nvcr.io/nvidia/auto-magic-calib:2.0.0           Up (healthy)
auto-magic-calib-ui-1   nvcr.io/nvidia/auto-magic-calib-ui:2.0.0        Up

Étape 6 : Vérifier que les Services s'Exécutent

# Lire les ports à partir de .env
MS_PORT=$(grep AUTO_MAGIC_CALIB_MS_PORT $REPO_ROOT/compose/.env | cut -d= -f2)
UI_PORT=$(grep AUTO_MAGIC_CALIB_UI_PORT $REPO_ROOT/compose/.env | cut -d= -f2)
HOST_IP=$(grep HOST_IP $REPO_ROOT/compose/.env | cut -d= -f2)

# Attendre la préparation du microservice. Les pulls d'images froides ou le premier démarrage
# peuvent nécessiter du temps supplémentaire après que `docker compose up -d` retourne.
READY_URL="http://localhost:${MS_PORT}/v1/ready"
echo "Waiting for microservice readiness at ${READY_URL} ..."
ready_response=""
for attempt in $(seq 1 24); do
  if ready_response=$(curl -fsS --max-time 5 "${READY_URL}" 2>/dev/null) && \
     echo "${ready_response}" | grep -q '"code"[[:space:]]*:[[:space:]]*0'; then
    echo "Microservice ready: ${ready_response}"
    break
  fi
  if [ "${attempt}" -lt 24 ]; then
    printf "  [%02d/24] Microservice not ready yet; retrying in 5s...\n" "${attempt}"
    sleep 5
  fi
done

if ! echo "${ready_response}" | grep -q '"code"[[:space:]]*:[[:space:]]*0'; then
  echo "ERROR: microservice did not report ready within 120 seconds: ${READY_URL}" >&2
  echo "Check status and logs:" >&2
  echo "  cd ${REPO_ROOT}/compose && docker compose ps" >&2
  echo "  cd ${REPO_ROOT}/compose && docker compose logs auto-magic-calib-ms" >&2
  exit 1
fi

# Vérifier que l'UI fonctionne
UI_STATUS=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 "http://localhost:${UI_PORT}")
if [ "${UI_STATUS}" != "200" ]; then
  echo "ERROR: Web UI returned HTTP ${UI_STATUS}; check docker compose ps and UI logs." >&2
  exit 1
fi
echo "Web UI ready: HTTP ${UI_STATUS}"

echo "Microservice: http://${HOST_IP}:${MS_PORT}"
echo "Web UI:       http://${HOST_IP}:${UI_PORT}"

Critères de Succès

Les deux conteneurs s'exécutent — voir la sortie docker compose ps de l'étape 5. Les deux services doivent afficher un statut « Up » ; le microservice doit afficher « (healthy) » dans la colonne STATUS.

Le microservice est sain — le sondage de préparation de l'étape 6 retourne code:0 depuis /v1/ready et affiche l'URL du service.

L'UI web est accessible :

• Ouvrir navigateur : http://<HOST_IP>:<AUTO_MAGIC_CALIB_UI_PORT>
• Doit afficher l'interface web AutoMagicCalib
• Doit pouvoir créer des projets et exécuter la calibrage

Sortie Clé

Microservice : http://<HOST_IP>:<AUTO_MAGIC_CALIB_MS_PORT> (port par défaut 8000)

• Docs API : http://<HOST_IP>:<AUTO_MAGIC_CALIB_MS_PORT>/docs

UI Web : http://<HOST_IP>:<AUTO_MAGIC_CALIB_UI_PORT> (port par défaut 5000)

• Gestion interactive de projets
• Interface de téléchargement de fichiers
• Configuration du calibrage
• Monitoring du statut en temps réel
• Visualisation et téléchargement des résultats

Persistance des Données :

• Projets stockés : $REPO_ROOT/projects/
• État persisté : $REPO_ROOT/projects/state.json

Dépannage

Corrections Courantes :

cd $REPO_ROOT/compose

# Afficher les logs
docker compose logs -f

# Afficher les logs d'un service spécifique
docker compose logs -f auto-magic-calib-ms

# Redémarrer tous les services
docker compose restart

# Arrêter et supprimer les conteneurs
docker compose down

# Mettre à jour .env et relancer
docker compose up -d

Arrêter les Services

cd $REPO_ROOT/compose

# Arrêter tous les services (conteneurs supprimés, données persistées)
docker compose down

# Arrêter et supprimer les volumes
docker compose down -v

Compétences Associées

• skills/amc-run-sample-calibration/SKILL.md - Vérifier le fonctionnement de la stack avec le dataset exemple inclus
• skills/amc-run-video-calibration/SKILL.md - Calibrer à partir de vos propres MP4 pré-enregistrés via API REST

<!-- signing marker -->