Regalamiunsorriso/.github/instructions/regalamiunsorriso-faceai-pve02docker.instructions.md

description	applyTo
Use when: debugging, inspecting, or updating the FaceAI Docker deployment on root@pve02docker.maddo.science, especially for faceai/** and stacks/faceai.yml changes.	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:

ssh root@pve02docker.maddo.science

From PowerShell on Windows, prefer invoking the SSH binary directly instead of wrapping it in cmd /c:

& '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 ... --% <remote command> 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:

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/<searchId>/worker.log
• /mnt/storage/data/faceai/logs/searches/<searchId>/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:

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:

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:

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:

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.