docs/deployment-hf.md

Visual Mentor v2: private Hugging Face staging and rollback

Prepared only. No Space has been created, uploaded or modified. Current production target Leon4gr45/openweb is protected by explicit approval and a staging UI review. No DGX/Needle/inference infrastructure change is required.

Local package and evidence

Docker runs Node/Next.js and one FastAPI worker, supervised by scripts/cloud-start.py. Only port 7860 is exposed. FastAPI binds loopback 8000. One authoritative web/next.config.ts preserves /api and /media, with Range seeking and bounded 65MB proxy buffering for the application's 64MiB upload cap. Node/Python bases are pinned. No torch, transformers, Whisper weights, CUDA runtime or GPU device is required. FFmpeg/age are CPU media/encryption tools, not inference models.

Build in this managed environment (session CA is mounted only during install):

BUILDX_CONFIG=/tmp/v2-buildx docker --host=unix:///var/run/docker.sock build \
  --secret id=build_ca,src=/etc/ssl/certs/ca-certificates.crt \
  -t video-rag-mentor:v2-review .
python scripts/qualify-release.py --image video-rag-mentor:v2-review
VM_RUNTIME_IMAGE=video-rag-mentor:v2-review python scripts/measure-runtime.py

These checks publish no host ports, run with network=none and a 2-vCPU/16GiB limit, and remove their own containers/volumes. Qualification checks application bearer roles, origin rejection, configuration CAS/rollback and volume recreation. A Docker volume in a test is not evidence that HF supplies durable storage.

Configuration before staging

Use HF Settings / Secrets (do not put values in YAML or browser bundles):

• VM_USER_TOKEN, VM_ADMIN_TOKEN: separate random tokens, >=24 characters. The user token opens private library/capture operations; admin token opens config and backup status only. This is a shared-role app, not per-person accounts/SSO.
• VM_ALLOWED_ORIGINS=https://<staging-app-host>: exact external origin.
• VM_ALLOWED_HOSTS: exact approved inference hostnames only.
• VRAG_DATA=/app/work/data, VM_STATE_DIR=/app/work/state; default index under /app/work/data/index. Configure GitHub-native backup and protected age identity as documented in backup-restore.md; the working disk remains ephemeral.
• LAYA_BASE_URL is the router root; OpenAI-compatible VLM/embedding/Whisper base URLs generally include /v1. Credential environment references are the exact api_key_secret fields in the reviewed profile. Do not assume all endpoints share a protocol or that NVIDIA's public API implements this /detect gateway.
• Backup settings, protected trigger and empty-state startup recovery: see backup-restore.md. No plaintext export is exposed.
• Decide whether answer-history persistence (VRAG_SAVE_ANSWERS) is permitted. Persisted answer history is included in encrypted GitHub checkpoints; review its privacy scope and opt out of local history if required.

All profile examples are disabled until model IDs, endpoints, capabilities, privacy trust and credentials are explicitly verified. Active placeholder IDs are rejected. Load/import YAML, review form/diff, validate, then apply using the current revision. Credentials remain server-only references. Transcripts/keyframes uploaded through Import may be sent to the selected authorized providers.

Mandatory approval and external gates

1. Approve a private staging Space (proposed Leon4gr45/openweb-v2-staging), GitHub backup storage budget and recovery integration. Obtain a fine-grained HF identity limited to intended repos. The current environment has no configured HF identity; openweb source, visibility, settings and screenshots were not inspected.
2. Before touching production, snapshot the existing Space Git revision, settings inventory (secret names only), private access policy and all data. Verify restore.
3. Qualify GitHub-native encrypted release assets and repository checkpoints as the sole recovery store. HF CPU Basic has 50GB ephemeral disk; no persistent mount or external object store is required. Complete the live GitHub destructive recovery drill and private Actions sleep/wake test in backup-restore.md.
4. Review docs/v2-evidence/main/ against current Playwright screenshots. Confirm original workflows remain recognizable at desktop/laptop/tablet/mobile sizes.
5. With explicit staging approval, create a private Docker Space and upload the reviewed source, using the official SDK and environment-provisioned HF_TOKEN:

import os
from huggingface_hub import HfApi
api = HfApi(token=os.environ['HF_TOKEN'])
repo = 'Leon4gr45/openweb-v2-staging'  # approved staging name
api.create_repo(repo_id=repo, repo_type='space', space_sdk='docker', private=True)
api.upload_folder(
    repo_id=repo, repo_type='space', folder_path='.',
    allow_patterns=['README.md', 'Dockerfile', 'requirements-runtime.txt',
                    'vrag/**', 'config/**', 'scripts/cloud-start.py', 'web/**'],
    ignore_patterns=['**/.env*', '**/*.pem', '**/*.key', '**/*.agekey', '**/*.age',
                     '**/__pycache__/**', '**/node_modules/**', '**/.next/**',
                     'web/tests/**', 'web/test-results/**', 'web/playwright-report/**'],
    commit_message='Stage reviewed Video RAG Visual Mentor v2',
)

6. Configure secrets/variables in staging, select CPU Basic (2 vCPU/16GB), inspect logs and health. Verify actual Space privacy by anonymous page/API/media requests; verify logged-in access with app user/admin roles and no access cross-over. Exercise /, /search, /ask, /experiments, /architecture, detail/clip Range seeking, /live and /models. Public sample assets are synthetic but still sit behind the private HF page/access boundary.
7. From a physical laptop browser over HTTPS, test laptop + USB simultaneous selection, permission denial/contention, disconnect, hidden-tab cleanup and stale results. Verify each real provider and costs using approved media only. Run real upload→Whisper→segments→embeddings→Search/Ask and verify citations/playback.
8. Recreate staging and restore all media/index/configuration from GitHub alone with the protected age key. Confirm a real recent checkpoint survives Space recreation. Mock transport tests alone do not pass this gate.
9. Present actual staging screenshots, provider test table, storage/backup/restore history and performance; obtain explicit approval before changing openweb.

Controlled production switch / rollback

Save the existing production Space commit and tested GitHub checkpoint IDs before upload. Obtain UI and deployment approval. Deploy the reviewed v2 source using the same procedure targeted at openweb; do not merge the deployment PR wholesale. Keep previous image/source and compatible snapshot available. On failure, pause writes, restore the previous Space revision and point at an isolated verified compatible state snapshot. Do not overwrite current data by automated restore or run the legacy serve/ scripts. Recheck private access, API/media and clips after rollback. Production promotion and rollback execution are operator actions.