thiagomoreiraboby/monitor-ubuntu-server repository overview

⁠Configuração e Uso

Este documento descreve como subir a ferramenta, o efeito de cada parâmetro e os cuidados de configuração em cada modo.

⁠Imagem Docker

Imagem publicada:

thiagomoreiraboby/monitor-ubuntu-server:latest

⁠Modos de coleta

⁠MONITOR_MODE=local

Use quando o container estiver no mesmo host Ubuntu que será monitorado.

Esse modo deve ser executado com pid: host ou --pid host. Sem isso, a lista de processos pode refletir apenas o namespace do container.

Requisitos:

• bind mount do host em /hostfs
• compartilhamento do namespace de PID do host
• acesso somente leitura é suficiente para o filesystem do host
• lm-sensors configurado no host para temperaturas
• NVIDIA Container Toolkit, se quiser telemetria de GPU NVIDIA dentro do container

Exemplo com docker run:

docker run -d \
  --name monitor-ubuntu-server \
  --restart unless-stopped \
  --pid host \
  -p 8080:8080 \
  -e MONITOR_MODE=local \
  -e MONITOR_TARGET_NAME="Ubuntu Local" \
  -e HOST_ROOT=/hostfs \
  -e HOST_PROC=/proc \
  -e PORT=8080 \
  -e REFRESH_SECONDS=5 \
  -v /:/hostfs:ro,rslave \
  thiagomoreiraboby/monitor-ubuntu-server:latest

⁠MONITOR_MODE=ssh

Use quando quiser monitorar outro Ubuntu sem instalar a aplicação nele.

Requisitos no host remoto:

• python3
• ps
• lm-sensors, se quiser sensores térmicos
• nvidia-smi, se quiser GPU NVIDIA

Exemplo:

docker run -d \
  --name monitor-ubuntu-server \
  --restart unless-stopped \
  -p 8080:8080 \
  -e MONITOR_MODE=ssh \
  -e MONITOR_TARGET_NAME="Servidor Remoto" \
  -e SSH_HOST=192.168.1.50 \
  -e SSH_PORT=22 \
  -e SSH_USER=ubuntu \
  -e SSH_KEY_PATH=/run/secrets/id_rsa \
  -v C:/Users/thiag/.ssh/id_rsa:/run/secrets/id_rsa:ro \
  thiagomoreiraboby/monitor-ubuntu-server:latest

⁠Parâmetros

⁠MONITOR_MODE

• Valores válidos: local, ssh
• Padrão: local
• Controla qual estratégia de coleta será usada.

⁠MONITOR_TARGET_NAME

• Padrão: Ubuntu Host
• Define o nome exibido no topo do dashboard e nas respostas da API.

⁠HOST_ROOT

• Padrão: /hostfs se existir, senão /
• Usado no modo local para calcular armazenamento com base no filesystem real do host.
• Não tem efeito prático no modo ssh.

⁠HOST_PROC

• Padrão: /proc
• Usado no modo local para ler CPU, memória, rede, processos e tabela de mounts.
• Com pid: host, esse caminho já representa o /proc do host.
• Não tem efeito prático no modo ssh.

⁠PORT

• Padrão: 8080
• Porta interna onde o servidor HTTP sobe.
• Se alterar, ajuste também o mapeamento de portas do container.

Exemplo:

-e PORT=8090 -p 8090:8090

⁠REFRESH_SECONDS

• Padrão: 5
• Controla o intervalo sugerido de polling usado pela UI.

⁠SSH_HOST

• Obrigatória no modo ssh
• IP ou hostname do servidor remoto.

⁠SSH_PORT

• Padrão: 22
• Porta do SSH remoto.

⁠SSH_USER

• Obrigatória no modo ssh
• Usuário utilizado na conexão SSH.

⁠SSH_KEY_PATH

• Opcional
• Caminho da chave privada dentro do container.
• Se for usar arquivo do host, faça bind mount para dentro do container.

Exemplo:

-e SSH_KEY_PATH=/run/secrets/id_rsa \
-v /home/ubuntu/.ssh/id_rsa:/run/secrets/id_rsa:ro

⁠SSH_EXTRA_ARGS

• Opcional
• Permite passar argumentos adicionais para o comando ssh.
• O valor é dividido por espaços, então evite quoting complexo.

Exemplo:

-e SSH_EXTRA_ARGS="-o ConnectTimeout=5 -o ServerAliveInterval=10"

⁠Exemplos com Docker Compose

⁠Local

services:
  monitoramento-pc:
    image: thiagomoreiraboby/monitor-ubuntu-server:latest
    container_name: monitoramento-pc
    restart: unless-stopped
    pid: host
    environment:
      MONITOR_MODE: local
      MONITOR_TARGET_NAME: Ubuntu Host
      HOST_ROOT: /hostfs
      HOST_PROC: /proc
      PORT: 8080
      REFRESH_SECONDS: 5
    ports:
      - "8080:8080"
    volumes:
      - /:/hostfs:ro,rslave

⁠SSH

services:
  monitoramento-pc:
    image: thiagomoreiraboby/monitor-ubuntu-server:latest
    container_name: monitoramento-pc
    restart: unless-stopped
    environment:
      MONITOR_MODE: ssh
      MONITOR_TARGET_NAME: Servidor SSH
      PORT: 8080
      REFRESH_SECONDS: 5
      SSH_HOST: 192.168.1.50
      SSH_PORT: 22
      SSH_USER: ubuntu
      SSH_KEY_PATH: /run/secrets/id_rsa
    ports:
      - "8080:8080"
    volumes:
      - C:/Users/thiag/.ssh/id_rsa:/run/secrets/id_rsa:ro

⁠Endpoints

⁠GET /api/config

Resposta:

{
  "mode": "local",
  "target": "Ubuntu Host",
  "refresh_seconds": 5
}

⁠GET /api/metrics

Resposta:

{
  "collected_at": "2026-03-25T12:00:00+00:00",
  "mode": "local",
  "target": "Ubuntu Host",
  "summary": {},
  "snapshot": {}
}

⁠Limitações conhecidas

• GPU hoje está focada em NVIDIA via nvidia-smi
• sensores térmicos dependem do hardware e da disponibilidade do sensors
• em modo ssh, o alvo remoto precisa aceitar execução de python3 -
• SSH_EXTRA_ARGS não é parseado como shell completo
• em modo local, sem pid: host, a seção de processos não representa corretamente o host

⁠Troubleshooting

⁠O dashboard abre, mas sem métricas

Verifique:

• se /hostfs está montado no modo local
• se o serviço está com pid: host no modo local
• se SSH_HOST e SSH_USER estão corretos no modo ssh
• se a chave privada montada em SSH_KEY_PATH é legível dentro do container

⁠Os processos exibidos são do container, não do host

Verifique:

• se o container foi iniciado com pid: host
• se HOST_PROC está apontando para /proc
• se você realmente está usando MONITOR_MODE=local

⁠O armazenamento mostra mounts estranhos de container

Verifique:

• se o host está montado em /hostfs
• se o serviço foi recriado após a última atualização da imagem
• se o modo em uso é local

⁠A GPU não aparece

Verifique:

• se nvidia-smi funciona no host
• se o container recebeu acesso à GPU
• se o host remoto tem driver NVIDIA instalado

⁠As temperaturas não aparecem

Verifique:

• se lm-sensors está instalado
• se sensors-detect --auto já foi executado
• se o hardware realmente expõe sensores suportados