--- description: 'Use when: debugging, inspecting, or updating the FaceAI Docker deployment on root@pve02docker.maddo.science, especially for faceai/** and stacks/faceai.yml changes.' applyTo: 'faceai/**, stacks/faceai.yml' --- # Regalami Un Sorriso FaceAI Docker Host Instructions in this file are specific to the FaceAI Docker deployment reachable as `root@pve02docker.maddo.science` through the preconfigured SSH tunnel and stored credentials. ## Host Access - SSH target: `root@pve02docker.maddo.science` - Plain `ssh root@pve02docker.maddo.science` works in the current environment. - The remote shell is `/bin/bash`, not `tcsh`. - Do not add manual tunnel, key, or credential flags unless the current workflow is revalidated. ## Preferred SSH Workflow For routine inspection, use plain SSH: ```powershell ssh root@pve02docker.maddo.science ``` From PowerShell on Windows, prefer invoking the SSH binary directly instead of wrapping it in `cmd /c`: ```powershell & 'C:\Windows\System32\OpenSSH\ssh.exe' 'root@pve02docker.maddo.science' ``` When you must run a single remote command non-interactively, pass the whole remote command as one SSH argument. ## Shell Behavior From PowerShell - Prefer one remote command per SSH invocation when doing reconnaissance. Complex commands with pipes, grouped expressions, or escaped parentheses are more likely to break under PowerShell-to-SSH quoting. - On Windows PowerShell, avoid `cmd /c "ssh ..."` wrappers for anything nontrivial. Nested quoting can collapse before SSH runs and spill later tokens into the local PowerShell session. - Prefer the PowerShell call operator form `& 'C:\Windows\System32\OpenSSH\ssh.exe' ...` and pass the remote command as a single argument when you must stay non-interactive. - If PowerShell shows the continuation prompt `? >`, the command was malformed locally before SSH executed it. Cancel it and rerun a simpler command instead of trying to answer the prompt. - When running remote commands from PowerShell, quoting can break if the command contains both nested quotes and file paths with spaces. - For read-only verification commands from PowerShell, prefer `ssh ... --% ` so the remote command is passed verbatim. - If repeated SSH commands start cancelling or interleaving poorly in the same terminal, rerun them sequentially instead of in parallel. - The remote shell is normal `bash`, so standard POSIX shell constructs usually work once they reach the host intact. ## Docker Runtime Facts - The FaceAI deployment is currently managed by Docker Compose, not Docker Swarm. - Compose project: `faceai` - Compose working directory: `/data/compose/4` - Compose file: `/data/compose/4/docker-compose.yml` - Main containers: - `regalami-faceai` - `regalami-faceai-processor` - `regalami-faceai-redis` ## Container Roles - `regalami-faceai`: public HTTP application - `regalami-faceai-processor`: background queue worker that runs the matcher jobs - `regalami-faceai-redis`: Redis queue and state store ## Useful Runtime Paths - Runtime data: `/mnt/storage/data/faceai/runtime` - Persistent logs: `/mnt/storage/data/faceai/logs` - Read-only PKL dataset: `/mnt/nas12/nas2/RUS` - In-container runtime root: `/data/runtime` - In-container log root: `/data/logs` - In-container PKL root: `/data/pkl` ## Logs And Health Checks Prefer Docker logs first for quick inspection: ```bash docker logs --tail 200 regalami-faceai docker logs --tail 200 regalami-faceai-processor docker logs --tail 200 regalami-faceai-redis ``` Persistent host logs are also available directly: - `/mnt/storage/data/faceai/logs/backend.log` - `/mnt/storage/data/faceai/logs/processor.log` - `/mnt/storage/data/faceai/logs/searches//worker.log` - `/mnt/storage/data/faceai/logs/searches//matcher.log` Operational notes: - `regalami-faceai` has shown `ECONNREFUSED` errors when Redis was not yet reachable, then recovered once Redis became healthy. - `docker ps` health output is meaningful here because the public app has an HTTP healthcheck and Redis has a readiness check. - If the public app is running but marked `unhealthy`, inspect both `docker logs regalami-faceai` and `/mnt/storage/data/faceai/logs/backend.log` before changing anything. ## Read-Only Debugging Commands Use these patterns before considering any state-changing action: ```bash docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Image}}' docker compose -f /data/compose/4/docker-compose.yml ps docker inspect regalami-faceai docker inspect regalami-faceai-processor docker inspect regalami-faceai-redis ``` When you need recent logs without attaching to a live stream: ```bash docker logs --tail 200 regalami-faceai docker logs --tail 200 regalami-faceai-processor docker logs --tail 200 regalami-faceai-redis ``` When you need file-backed diagnostics: ```bash tail -n 200 /mnt/storage/data/faceai/logs/backend.log tail -n 200 /mnt/storage/data/faceai/logs/processor.log ``` ## Updates And Container Management If the user explicitly approves a rollout or image refresh, the Compose-managed update path is from `/data/compose/4`: ```bash cd /data/compose/4 docker compose pull docker compose up -d ``` After any approved update, verify with: - `docker compose -f /data/compose/4/docker-compose.yml ps` - `docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.RunningFor}}'` - `docker logs --tail 200 regalami-faceai` - `docker logs --tail 200 regalami-faceai-processor` ## Consent Rules Read-only inspection may proceed without additional confirmation. Any destructive or service-affecting action requires the user's express consent, and that consent must be collected through the `vscode_askQuestions` tool before running the command. Treat all of the following as consent-gated actions: - `docker compose pull` - `docker compose up -d` - `docker compose down` - `docker restart`, `docker stop`, `docker kill`, `docker rm` - `docker exec` commands that modify files, data, or runtime state - deleting logs, runtime files, volumes, images, networks, or containers - `docker system prune`, `docker volume prune`, and similar cleanup commands - editing files under `/data/compose/4` or the mounted FaceAI host paths Before any consent-gated action, ask a concise confirmation question that names the exact action and the affected services. ## Safety Boundaries - Default to inspection first. Do not jump directly to restarts or updates when logs or status already explain the issue. - Do not run cleanup commands opportunistically. - Do not edit Compose files on the host unless the user explicitly asks for that change. - Do not assume that `regalami-faceai` startup errors are frontend issues. Check Redis reachability, processor availability, and mounted log files first. - If a command may produce a long interactive stream, prefer a bounded `docker logs --tail ...` read before following with a live stream.