IoT Sentinel — Instalação e Setup em 5 Minutos com Docker Compose

iot homelab docker monitoring tutorial

IoT Sentinel — Instalação e Setup em 5 Minutos com Docker Compose

Este post é o segundo de uma série de oito partes sobre o IoT Sentinel. Aqui mostro como instalar e fazer o setup inicial.

Pré-requisitos

Antes de começar, você precisa de:

  • Docker e Docker Compose instalados. Se ainda não tem, a documentação oficial do Docker cobre a instalação para qualquer sistema operacional.
  • Portas 9000 e 9001 livres no host. A porta 9000 é o frontend e a 9001 é a API. Se alguma estiver ocupada, você pode trocar no compose (explico mais abaixo no troubleshooting).
  • Linux recomendado se você quiser scan de rede real. O worker usa network_mode: host para rodar nmap diretamente na rede do host. No Docker Desktop (Windows/macOS), isso não funciona da mesma forma, então o worker entra automaticamente em mock mode — ele simula dispositivos para você testar a interface sem precisar de uma rede real.

Instalação

São dois comandos. Primeiro, baixe o arquivo docker-compose.prod.yml do repositório:

curl -O https://raw.githubusercontent.com/mauricioj/iot-sentinel/main/docker-compose.prod.yml

Depois, suba tudo:

docker compose -f docker-compose.prod.yml up -d

O Docker vai baixar as imagens do Docker Hub e iniciar cinco containers. Dependendo da sua conexão, o primeiro up pode levar alguns minutos por causa do download. Nas próximas vezes é instantâneo.

O que cada container faz

  • frontend (mauricioj/iot-sentinel-frontend:latest) — Interface web em Next.js. Roda internamente na porta 3000, exposta na porta 9000 do host. É onde você vai interagir com a plataforma.

  • api (mauricioj/iot-sentinel-api:latest) — Backend REST API + WebSocket em NestJS. Roda na porta interna 4000, exposta na porta 9001. Cuida de autenticação, CRUD de dispositivos, orquestração de scans e notificações em tempo real.

  • worker (mauricioj/iot-sentinel-worker:latest) — Worker em Python que executa scans de rede via nmap e health checks dos dispositivos. Roda em network_mode: host para ter acesso direto à rede. Consome jobs de uma fila Redis.

  • mongodb (mongo:7) — MongoDB 7 para persistência de todos os dados: dispositivos, locais, redes, credenciais criptografadas, histórico de status.

  • redis (redis:7-alpine) — Redis 7 para filas de jobs (Bull) e pub/sub. É o canal de comunicação entre a API e o worker.

Todos os dados são persistidos em Docker volumes (mongodb_data, redis_data, api_secrets), então você pode parar e reiniciar os containers sem perder nada.

Primeiro acesso: Setup Wizard

Com os containers rodando, abra o browser e acesse:

http://localhost:9000

No primeiro acesso, o IoT Sentinel detecta que não existe nenhum usuário no sistema e redireciona automaticamente para o Setup Wizard. Ele pede três coisas:

  1. Dados do admin — username, email e senha. Esse será o primeiro usuário com permissão total no sistema.
  2. Idioma — Português (pt-BR) ou English. Isso define o idioma da interface inteira, incluindo os tipos de dispositivos pré-cadastrados (ex: “Roteador” vs “Router”).

Depois de preencher, clique em finalizar. O sistema cria o usuário, gera a chave de criptografia para credenciais (AES-256-GCM, salva em um Docker volume), faz o seed dos 19 tipos de dispositivos padrão, e redireciona para a tela de login.

Faça login com as credenciais que acabou de criar e pronto — você está dentro.

Conhecendo a interface

Depois do login, você cai no Dashboard. Na lateral esquerda tem a sidebar com a navegação principal:

  • Dashboard — Visão geral com contadores e status
  • Locais — Seus locais físicos (escritório, datacenter, site remoto)
  • Dispositivos — Lista completa de todos os devices cadastrados
  • Grupos — Labels transversais para organizar dispositivos por função
  • Configurações — Usuários, idioma, backup e restore

Neste momento, o dashboard vai mostrar tudo zerado: zero locais, zero dispositivos, zero redes. Tudo zerado por enquanto — mas isso muda rápido nos próximos posts, quando vamos cadastrar locais, rodar o primeiro scan e começar a popular o inventário.

Troubleshooting

Porta ocupada

Se a porta 9000 ou 9001 já estiver em uso por outro serviço, você pode trocar diretamente no compose. Crie um arquivo .env no mesmo diretório do docker-compose.prod.yml:

FRONTEND_PORT=9100
API_PORT=9101

E suba novamente com docker compose -f docker-compose.prod.yml up -d. O compose lê o .env automaticamente.

Container não sobe

Verifique os logs do serviço que está com problema:

docker compose -f docker-compose.prod.yml logs api
docker compose -f docker-compose.prod.yml logs frontend
docker compose -f docker-compose.prod.yml logs worker

Na maioria dos casos, o problema é ordem de inicialização — o api depende do mongodb e do redis, e o frontend depende do api. Se o mongo demorar para inicializar, a API pode falhar na primeira tentativa. Com restart: unless-stopped configurado no compose, o Docker reinicia automaticamente e tudo se estabiliza em alguns segundos.

Frontend não carrega

Se o frontend abriu mas mostra tela em branco ou erro de conexão, verifique se a API está respondendo:

curl http://localhost:9001/health

Você deve receber um JSON com o status dos serviços. Se não responder, olhe os logs da API.

Worker sem scan real

Se você está no Docker Desktop (Windows ou macOS), o worker vai operar em mock mode automaticamente. Isso é esperado. A variável SCANNER_MOCK_MODE vem configurada como auto no compose, e o worker detecta que não tem acesso real à rede do host. Ele vai simular dispositivos para que você possa testar toda a interface. Para scans reais, rode em um host Linux com Docker Engine nativo.

Próximo passo

Com o IoT Sentinel rodando e o admin criado, o próximo passo é criar sua estrutura de locais e redes. Na Parte 3 — Locais, Redes e VLANs, mostro como modelar seus ambientes físicos e segmentos de rede dentro da plataforma.