# Node-RED IoT Platform

> Node-RED flow-based programming for IoT with MQTT broker.

- Category: Home Lab & Self-Hosting
- Difficulty: beginner
- Components: node-red, mosquitto
- Tags: node-red, iot, mqtt, automation, flow-programming
- Source: https://docker.recipes/homelab/node-red-iot

## Overview

Node-RED is an open-source flow-based visual programming tool originally developed by IBM for wiring together hardware devices, APIs, and online services in IoT applications. Built on Node.js, it provides a browser-based flow editor that makes it easy to create event-driven applications using a wide range of pre-built nodes. The platform excels at rapid prototyping and deployment of IoT solutions, home automation systems, and data processing workflows without requiring traditional programming skills.

This stack combines Node-RED with Eclipse Mosquitto, a lightweight MQTT message broker that implements the MQTT protocol versions 5.0, 3.1.1, and 3.1. Mosquitto serves as the central communication hub for IoT devices, while Node-RED acts as the orchestration layer, processing MQTT messages and triggering automated responses. The integration enables real-time data collection from sensors, device control commands, and complex automation logic through Node-RED's visual drag-and-drop interface.

This configuration is ideal for IoT enthusiasts, home automation builders, and small-scale industrial deployments who need a powerful yet approachable platform for connecting and controlling smart devices. The combination provides enterprise-grade MQTT messaging capabilities with the flexibility of visual flow programming, making it accessible to both technical and non-technical users who want to build sophisticated IoT applications.

## Features

- Flow-based visual programming with drag-and-drop node editor for creating IoT automation logic
- Built-in MQTT nodes for seamless publish/subscribe messaging with Mosquitto broker
- Over 4,000 community-contributed nodes available through npm for extending functionality
- Real-time dashboard creation with gauge, chart, and control widgets for IoT monitoring
- Function nodes supporting JavaScript for custom data processing and transformation
- WebSocket support for real-time browser-based device interaction and monitoring
- Eclipse Mosquitto MQTT 5.0 compliance with quality of service levels and retained messages
- Persistent flow storage with automatic backup and version control capabilities

## Use cases

- Home automation systems controlling smart lights, thermostats, and security sensors via MQTT
- Industrial IoT monitoring with sensor data collection and equipment status dashboards
- Greenhouse automation managing irrigation, climate control, and environmental monitoring
- Smart building management integrating HVAC, lighting, and occupancy sensors
- Weather station data aggregation with automated alerts and historical data logging
- Fleet vehicle tracking and monitoring using GPS and telemetry data over MQTT
- Energy monitoring systems tracking solar panels, battery storage, and consumption patterns

## Prerequisites

- Docker Engine 20.10+ and Docker Compose V2 for container orchestration
- Minimum 512MB RAM for Node-RED container and 256MB for Mosquitto broker
- Available ports 1880 (Node-RED), 1883 (MQTT), and 9001 (MQTT WebSocket)
- Basic understanding of MQTT publish/subscribe messaging concepts
- Mosquitto configuration file (mosquitto.conf) with authentication and access control settings
- Network access for downloading Node-RED community nodes from npm registry

## docker-compose.yml

```yaml
services:
  mosquitto:
    image: eclipse-mosquitto:latest
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "${MQTT_PORT:-1883}:1883"
      - "${MQTT_WS_PORT:-9001}:9001"
    volumes:
      - mosquitto_data:/mosquitto/data
      - mosquitto_log:/mosquitto/log
      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf:ro
    networks:
      - iot-network

  node-red:
    image: nodered/node-red:latest
    container_name: node-red
    restart: unless-stopped
    ports:
      - "${NODERED_PORT:-1880}:1880"
    environment:
      - TZ=${TZ:-UTC}
    volumes:
      - nodered_data:/data
    depends_on:
      - mosquitto
    networks:
      - iot-network

volumes:
  mosquitto_data:
  mosquitto_log:
  nodered_data:

networks:
  iot-network:
    driver: bridge
```

## .env

```bash
# Node-RED IoT
NODERED_PORT=1880
MQTT_PORT=1883
MQTT_WS_PORT=9001
TZ=UTC
```

## Usage notes

- Node-RED at http://localhost:1880
- MQTT broker at localhost:1883
- Create mosquitto.conf before starting
- Install MQTT nodes in Node-RED

## Troubleshooting

- Node-RED flows not saving: Check that the /data volume has proper write permissions and sufficient disk space
- MQTT clients cannot connect to Mosquitto: Verify mosquitto.conf allows anonymous connections or configure proper authentication
- Node-RED MQTT nodes show 'disconnected': Ensure Mosquitto container is running and check network connectivity between containers
- WebSocket connections failing on port 9001: Confirm Mosquitto configuration includes WebSocket listener and port is not blocked by firewall
- Node-RED dashboard not loading: Clear browser cache and check that ui nodes are properly installed and configured
- High memory usage in Node-RED: Reduce debug node output retention and limit the number of active dashboard charts

