monitorRPi/DOCUMENTACION.md

Monitor RPi Rack

Aplicacion web local para monitorizar un rack de Raspberry Pi mediante SSH. Corre en un contenedor Docker dedicado y expone un dashboard accesible por navegador.

Arquitectura

Navegador
  dashboard.html / config.html
        |
        | HTTP API
        v
Contenedor monitor-rpi
        |
        | SSH con usuario/password o clave asimetrica
        v
Raspberry Pi activas

El backend mantiene el ultimo estado en memoria. El dashboard consulta ese estado, pero no abre conexiones SSH directamente.

Rutas Principales

• Dashboard: http://192.168.0.53:8787/dashboard.html
• Configuracion: http://192.168.0.53:8787/config.html
• API estado: http://192.168.0.53:8787/api/status

Credenciales HTTP actuales:

usuario: admin
password: monitor-rpi-2026

Configuracion Persistente

La configuracion vive en:

/home/yamaray/docker/monitorRPi/data/config.json

Dentro del contenedor se lee como:

/data/config.json

Parametros Generales

mockMode

Si es true, el sistema genera datos simulados. Si es false, consulta las Raspberry reales por SSH.

refreshIntervalSeconds

Intervalo activo de escaneo cuando hay al menos un dashboard visible. Por defecto: 30.

idleScanIntervalSeconds

Intervalo lento de escaneo cuando no hay dashboards visibles. Por defecto: 300.

sshTimeoutSeconds

Tiempo maximo permitido para completar cada consulta SSH. Por defecto: 8.

temperatureThresholdsC

Umbrales de color para temperaturas:

{
  "warning": 60,
  "hot": 70,
  "critical": 80
}

metricThresholdsPercent

Umbrales por metrica para barras de CPU, RAM y disco.

Valores actuales recomendados:

{
  "cpu": { "warning": 60, "hot": 75, "critical": 90 },
  "memory": { "warning": 70, "hot": 85, "critical": 95 },
  "disk": { "warning": 70, "hot": 85, "critical": 95 }
}

Parametros Por Dispositivo

active

Si es true, el backend consulta ese dispositivo. Si es false, aparece como inactivo y no se abre SSH.

id

Identificador interno unico del dispositivo. Se usa para tracking interno y calculos como tasas de red.

name

Nombre visible en el dashboard.

host

IP o nombre DNS usado para conectar por SSH.

port

Puerto SSH. Normalmente 22; en Home Assistant puede ser 2222 si se usa un add-on SSH.

username

Usuario SSH.

password

Password SSH. Se guarda en config.json, por lo que el archivo debe permanecer protegido. Si el dispositivo usa authMethod: "key", no se usa password.

authMethod

Metodo de autenticacion SSH por dispositivo. Valores recomendados:

• password: usa username y password.
• key: usa username y la clave privada global configurada en sshPrivateKeyPath. Operativamente, instala la clave publica del monitor en la RPi.

privateKeyPath

Campo heredado para configuraciones antiguas con clave privada por dispositivo. La interfaz nueva usa la clave global del monitor y deja este campo vacio.

Autenticacion SSH por Clave Asimetrica

El monitor soporta dos metodos de autenticacion por dispositivo:

• Password SSH: usar password y dejar privateKeyPath vacio.
• Clave asimetrica: dejar password vacio, seleccionar authMethod: "key" y copiar la clave publica del monitor en la RPi.

Cuando un dispositivo tiene authMethod: "key", el backend usa la clave privada global configurada en sshPrivateKeyPath. El campo privateKeyPath por dispositivo queda solo como compatibilidad con configuraciones antiguas.

Configuracion global de claves

"sshPrivateKeyPath": "/ssh/monitor_rpi_ed25519",
"sshPublicKeyPath": "/ssh/monitor_rpi_ed25519.pub"

La clave privada se queda solo en el monitor. La clave publica se muestra en el configurador y puede copiarse o descargarse para instalarla en las RPi remotas.

1. Guardar la clave privada en el volumen del monitor

En la RPi donde corre el contenedor, guarda las claves en:

/home/yamaray/docker/monitorRPi/ssh

Ejemplo:

/home/yamaray/docker/monitorRPi/ssh/monitor_rpi_ed25519
/home/yamaray/docker/monitorRPi/ssh/monitor_rpi_ed25519.pub

La clave privada debe quedar protegida:

chmod 700 /home/yamaray/docker/monitorRPi/ssh
chmod 600 /home/yamaray/docker/monitorRPi/ssh/monitor_rpi_ed25519

El docker-compose.yml debe montar esa carpeta dentro del contenedor:

volumes:
  - /home/yamaray/docker/monitorRPi/app:/app:ro
  - /home/yamaray/docker/monitorRPi/data:/data
  - /home/yamaray/docker/monitorRPi/ssh:/ssh:ro

Dentro de la configuracion del dispositivo, la ruta debe ser la ruta vista por el contenedor:

"authMethod": "key",
"password": "",
"privateKeyPath": ""

2. Instalar la clave publica en la Raspberry destino

En el dispositivo remoto, la clave publica debe agregarse al usuario SSH correspondiente.

Ejemplo para usuario pi:

mkdir -p ~/.ssh
chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

En authorized_keys pega el contenido de la clave publica:

monitor_rpi_ed25519.pub

El archivo correcto en Linux/OpenSSH es:

~/.ssh/authorized_keys

No es authorised_keys.

3. Probar la conexion desde el contenedor

Una vez montada la clave, puedes probar desde la RPi host:

docker exec -it monitor-rpi ssh -i /ssh/monitor_rpi_ed25519 -o IdentitiesOnly=yes pi@HOST_REMOTO

Si el dispositivo usa un puerto distinto:

docker exec -it monitor-rpi ssh -i /ssh/monitor_rpi_ed25519 -o IdentitiesOnly=yes -p 34000 pi@192.168.0.1

Si la conexion funciona sin pedir password, el monitor tambien podra consultar ese dispositivo.

model

Modelo visible: RPi 3, RPi 4, RPi 5.

role

Funcion del dispositivo: Docker, Home Assistant, MQTT, Nginx, Gitea, etc.

location

Ubicacion fisica o logica. Actualmente se muestra en la tarjeta.

Metricas Recogidas

Por SSH se leen datos de solo lectura:

• Temperatura CPU
• Temperatura Top-Rack opcional desde archivo JSON escrito por Node-RED
• Uso CPU
• Uso RAM
• Uso disco raiz /
• Load average
• Uptime
• Docker instalado
• Contenedores Docker activos
• Contenedores Docker detenidos
• Contenedores Docker unhealthy
• Interfaz de red principal
• Tipo de conexion: Cable/WiFi
• Velocidad nominal si existe
• Trafico RX/TX calculado entre scans

Temperatura Top-Rack

Si una RPi tiene un sensor externo de temperatura del rack, Node-RED puede escribir la lectura en un archivo local del mismo equipo:

{
  "temperatureC": 23.7,
  "sensor": "rack-top",
  "updatedAt": "2026-06-05T21:12:18.997Z"
}

En el configurador, coloca la ruta en el dispositivo que tiene el sensor:

/home/yamaray/monitor-rpi/rack-temp.json

El backend lee ese archivo durante el mismo scan SSH y muestra el valor como Temperatura Top-Rack en la primera linea del dashboard.

Clientes Activos

El dashboard envia heartbeat al backend cuando esta visible.

Comportamiento:

0 clientes visibles -> escaneo lento idleScanIntervalSeconds
1+ clientes visibles -> escaneo activo refreshIntervalSeconds

El navegador integrado de Codex se ignora para no alterar el conteo de clientes reales.

API

Todas las llamadas requieren autenticacion HTTP Basic.

GET /api/status

Devuelve ultimo estado conocido.

Incluye:

• mockMode
• refreshIntervalSeconds
• idleScanIntervalSeconds
• activeClients
• currentScanIntervalSeconds
• temperatureThresholdsC
• metricThresholdsPercent
• summary
• devices
• clients

Ejemplo PowerShell:

$pair = 'admin:monitor-rpi-2026'
$token = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($pair))
Invoke-RestMethod http://192.168.0.53:8787/api/status -Headers @{Authorization="Basic $token"}

GET /api/config

Devuelve la configuracion actual.

Nota: actualmente devuelve tambien credenciales porque config.html permite editarlas. Protege el acceso HTTP y el archivo config.json.

POST /api/config

Guarda la configuracion completa y reinicia el ciclo de escaneo.

POST /api/reload

Recarga config.json desde disco.

POST /api/scan-now

Fuerza un scan inmediato de todos los dispositivos activos.

POST /api/client-heartbeat

Usado por el dashboard para avisar que hay un cliente visible.

Body:

{
  "clientId": "client-id"
}

POST /api/clients/clear

Limpia la lista de clientes activos en memoria.

Docker

Ruta en la RPi:

/home/yamaray/docker/monitorRPi/

Stack:

/home/yamaray/docker/monitorRPi/docker-compose.yml

Reiniciar:

cd /home/yamaray/docker/monitorRPi
docker compose restart monitor-rpi

Reconstruir:

cd /home/yamaray/docker/monitorRPi
docker compose up -d --build