Tutorial Node-RED + Mosquitto con Docker

En este tutorial levantarás un stack IoT completo con dos servicios Docker:

• Eclipse Mosquitto 2.0 — broker MQTT (el “cartero” de tus mensajes IoT)
• Node-RED — editor visual de flujos con dashboard en tiempo real

Arquitectura

[Sensores / Dispositivos IoT]
        │
        │  MQTT (puerto 1883)
        ▼
   ┌──────────────┐
   │  Mosquitto   │  ← broker MQTT, enruta mensajes
   └──────┬───────┘
          │  suscripción interna
          ▼
   ┌──────────────┐
   │   Node-RED   │  ← flujos visuales, lógica, dashboard
   └──────────────┘
          │
          ▼
   http://localhost:1880/dashboard

Prerrequisitos

• Docker y Docker Compose instalados
• Conocimientos básicos de terminal

---

Paso 1: Crear la estructura del proyecto

mkdir nodered-iot
cd nodered-iot
mkdir -p mosquitto/config

La estructura final será:

nodered-iot/
├── docker-compose.yml
└── mosquitto/
    └── mosquitto.conf

---

Paso 2: Configurar Mosquitto

Crea el archivo mosquitto/mosquitto.conf:

mosquitto/mosquitto.conf

# Puerto TCP estándar — sensores se conectan aquí
listener 1883
allow_anonymous true

# Puerto WebSocket — clientes de navegador
listener 9001
protocol websockets
allow_anonymous true

# Persistencia de mensajes retenidos
persistence true
persistence_location /mosquitto/data/
log_dest stdout

Nota

allow_anonymous true permite conexiones sin usuario/contraseña. Esto es adecuado para laboratorios y desarrollo. Para producción, consulta la guía de seguridad.

---

Paso 3: Crear el docker-compose.yml

docker-compose.yml

version: '3.8'

networks:
  iot-net:
    driver: bridge

volumes:
  nodered-data:
  mosquitto-data:
  mosquitto-log:

services:

  # ── 1. Eclipse Mosquitto — Broker MQTT ──────────────────────────────────
  mosquitto:
    image: eclipse-mosquitto:2.0
    container_name: mosquitto
    restart: unless-stopped
    networks:
      - iot-net
    ports:
      - "1883:1883"   # MQTT TCP — sensores se conectan aquí
      - "9001:9001"   # MQTT sobre WebSocket — clientes de navegador
    volumes:
      - ./mosquitto/mosquitto.conf:/mosquitto/config/mosquitto.conf:ro
      - mosquitto-data:/mosquitto/data
      - mosquitto-log:/mosquitto/log
    healthcheck:
      test: ["CMD", "mosquitto_sub", "-t", "$$SYS/#", "-C", "1", "-i", "healthcheck", "-W", "3"]
      interval: 15s
      timeout: 5s
      retries: 3

  # ── 2. Node-RED — Editor visual + Dashboard ──────────────────────────────
  node-red:
    image: nodered/node-red:latest
    container_name: node-red
    restart: unless-stopped
    networks:
      - iot-net
    ports:
      - "1880:1880"   # Editor de flujos y dashboard
    depends_on:
      mosquitto:
        condition: service_healthy
    volumes:
      - nodered-data:/data

Consejo

Docker resuelve automáticamente el hostname mosquitto dentro de la red iot-net. Node-RED puede conectarse al broker simplemente usando mosquitto como host, sin necesitar la IP del servidor.

---

Paso 4: Iniciar el stack y verificar

docker compose up -d

Espera ~15 segundos y verifica:

docker compose ps

Deberías ver ambos servicios en estado running (healthy).

Prueba de humo del broker MQTT

Abre una terminal y suscríbete a todos los topics:

# Suscribirse (en una terminal)
docker exec -it mosquitto mosquitto_sub -h localhost -t "#" -v

# Publicar un mensaje de prueba (en otra terminal)
docker exec -it mosquitto mosquitto_pub -h localhost -t "prueba/hola" -m "funciona!"

Deberías ver prueba/hola funciona! en la primera terminal. ✅

---

Paso 5: Instalar el Dashboard en Node-RED

1. Abre http://localhost:1880 en tu navegador
2. Haz clic en el menú ≡ (arriba a la derecha) → Manage palette
3. Ve a la pestaña Install
4. Busca @flowfuse/node-red-dashboard
5. Haz clic en Install → confirma

---

Paso 6: Crear tu primer flujo con datos MQTT

Flujo básico: recibir datos MQTT y mostrarlos en dashboard

En el editor de Node-RED, construye este flujo arrastrando nodos desde el panel izquierdo:

Configurar el nodo mqtt in:

• Haz doble clic en el nodo
• Server: haz clic en el lápiz para agregar nuevo servidor
  • Host: mosquitto
  • Port: 1883
• Topic: sensores/temperatura
• Output: a parsed JSON object

Configurar el nodo ui-gauge:

• Label: Temperatura
• Units: °C
• Range: 0 a 50

Configurar el nodo ui-chart:

• Label: Historial de temperatura
• Type: Line chart

Haz clic en Deploy/Instanciar (botón rojo arriba a la derecha).

Ver el dashboard

Abre http://localhost:1880/dashboard — verás los widgets esperando datos.

---

Paso 7: Enviar datos de prueba

Desde la terminal (mosquitto_pub)

# Enviar una lectura de temperatura
docker exec -it mosquitto mosquitto_pub \
  -h localhost \
  -t "sensores/temperatura" \
  -m '{\"value\": 23.4}'

# Enviar varias lecturas en bucle
for i in $(seq 1 10); do
  docker exec -it mosquitto mosquitto_pub \
    -h localhost \
    -t "sensores/temperatura" \
    -m "{\"value\": $((20 + RANDOM % 10))}"
  sleep 2
done

Verás los datos aparecer en tiempo real en el dashboard.

---

Paso 8: Conectar un dispositivo real

Desde Python (en la misma red LAN)

pip install paho-mqtt

import paho.mqtt.client as mqtt
import json
import time
import random

# Reemplaza con la IP de tu servidor
BROKER_IP = "192.168.1.100"

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
client.connect(BROKER_IP, 1883)

while True:
    temperatura = 20 + random.uniform(0, 10)
    payload = json.dumps({"value": round(temperatura, 2)})
    client.publish("sensores/temperatura", payload)
    print(f"Publicado: {payload}")
    time.sleep(5)

Desde Arduino / ESP32

#include <WiFi.h>
#include <PubSubClient.h>
#include <ArduinoJson.h>

const char* ssid     = "TU_WIFI";
const char* password = "TU_PASSWORD";
const char* broker   = "192.168.1.100";  // IP de tu servidor

WiFiClient   espClient;
PubSubClient client(espClient);

void setup() {
  Serial.begin(115200);
  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) delay(500);

  client.setServer(broker, 1883);
  client.connect("esp32-sensor");
}

void loop() {
  float temp = random(200, 350) / 10.0;  // Simula sensor

  StaticJsonDocument<64> doc;
  doc["value"] = temp;

  char buf[64];
  serializeJson(doc, buf);
  client.publish("sensores/temperatura", buf);

  delay(5000);
}

---

Paso 9: Comandos de depuración MQTT

# Suscribirse a TODOS los topics (wildcard #)
docker exec -it mosquitto mosquitto_sub -h localhost -t "#" -v

# Ver estadísticas del broker
docker exec -it mosquitto mosquitto_sub -h localhost -t '$SYS/#' -v -C 10

# Publicar mensaje retenido (llega a nuevos suscriptores inmediatamente)
docker exec -it mosquitto mosquitto_pub -h localhost -t "config/umbral" -m "30" -r

---

Paso 10 (Opcional): Agregar autenticación a Mosquitto

Para entornos más allá del laboratorio, habilita usuario y contraseña:

1. Crear archivo de contraseñas

# Crear el archivo con el primer usuario
docker exec -it mosquitto mosquitto_passwd -c /mosquitto/config/passwd usuario1

# Agregar más usuarios (sin -c para no sobrescribir)
docker exec -it mosquitto mosquitto_passwd /mosquitto/config/passwd usuario2

2. Actualizar mosquitto.conf

listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd

listener 9001
protocol websockets
allow_anonymous false
password_file /mosquitto/config/passwd

3. Reiniciar Mosquitto

docker compose restart mosquitto

4. Actualizar el nodo MQTT en Node-RED

En la configuración del servidor MQTT dentro de Node-RED, agrega las credenciales de usuario.

---

Referencia rápida de puertos

Puerto	Servicio	Uso
1880	Node-RED	Editor de flujos y dashboard
1883	Mosquitto	MQTT TCP (sensores, scripts)
9001	Mosquitto	MQTT WebSocket (navegadores)