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

---
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 ... --% <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:

```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/<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:

```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.