Cómo ejecutar Node-RED en Docker para proyectos MQTT

Ejecutar Node-RED en Docker te da una instalación reproducible, fácil de actualizar, respaldar y trasladar entre máquinas. En este tutorial arrancarás la imagen oficial de Node-RED para Docker, guardarás tus flujos en un volumen persistente, la gestionarás con Docker Compose, añadirás nodos adicionales, pasarás secretos de forma segura y conectarás el contenedor a un broker MQTT con TLS.

Por qué ejecutar Node-RED en Docker

Instalar Node-RED directamente con npm funciona bien, y nuestra guía para instalar Node-RED cubre ese camino. Los contenedores aportan algunas ventajas que importan en cuanto un flujo hace trabajo real:

• Versiones fijadas. Eliges la versión exacta de Node-RED y de Node.js mediante la etiqueta de la imagen, así que una actualización es un cambio deliberado.
• Separación limpia. Todo lo que escribe Node-RED vive en un único directorio, /data, que montas como volumen. Respalda esa carpeta y lo tendrás todo.
• Vuelta atrás sencilla. Si una actualización rompe un nodo de la comunidad, vuelve a la etiqueta anterior.
• La misma configuración en todas partes. Un archivo Compose se ejecuta igual en un portátil, en una Raspberry Pi con un sistema operativo de 64 bits o en una máquina virtual en la nube.

La imagen oficial es nodered/node-red en Docker Hub. Etiquetas como latest, una versión concreta como 4.0.9 o variantes con una versión específica de Node.js te permiten elegir hasta qué punto fijar la versión. En producción, fija una etiqueta de versión en lugar de latest.

Inicio rápido con docker run

Asegúrate de que Docker está instalado y ejecuta:

docker volume create node_red_data

docker run -d \
  --name nodered \
  --restart unless-stopped \
  -p 1880:1880 \
  -e TZ=Europe/Istanbul \
  -v node_red_data:/data \
  nodered/node-red:latest

Abre http://localhost:1880 y tendrás un editor funcionando. El parámetro importante es -v node_red_data:/data. Sin él, los flujos, los nodos instalados y las credenciales viven en la capa escribible del contenedor y desaparecen cuando lo eliminas o lo recreas. TZ define la zona horaria para que las marcas de tiempo y las programaciones de inject coincidan con tu hora local.

Comandos útiles del día a día:

docker logs -f nodered          # seguir el log de Node-RED
docker exec -it nodered bash    # shell dentro del contenedor
docker restart nodered          # reiniciar tras editar settings.js

La política --restart unless-stopped vuelve a levantar Node-RED automáticamente tras un fallo o un reinicio del host, pero no después de que lo detengas deliberadamente. Eso importa en los flujos MQTT: cuando el contenedor se reinicia, el nodo broker se reconecta por sí solo y las suscripciones se restauran desde el flujo, de modo que un gateway que se queda sin corriente se recupera sin que nadie lo toque. Combínalo con almacenamiento persistente, descrito a continuación, para que los flujos con los que se reinicia sean los que desplegaste.

Volumen con nombre o bind mount

Puedes montar un volumen con nombre, como arriba, o una carpeta del host:

mkdir -p ~/node-red-data
sudo chown -R 1000:1000 ~/node-red-data
docker run -d --name nodered -p 1880:1880 -v ~/node-red-data:/data nodered/node-red:latest

Un bind mount facilita editar y respaldar settings.js y flows.json desde el host. El inconveniente son los permisos: el contenedor ejecuta Node-RED como un usuario con UID 1000. Si la carpeta del host pertenece a root o a otro usuario, Node-RED no puede escribir y verás errores EACCES en el log. El chown anterior lo evita.

Un archivo Docker Compose listo para producción

Para cualquier cosa de larga duración, describe el contenedor en Compose. Este archivo fija la imagen, persiste los datos, define la zona horaria y pasa los secretos mediante un archivo de entorno:

# docker-compose.yml
services:
  nodered:
    image: nodered/node-red:4.0.9
    container_name: nodered
    restart: unless-stopped
    ports:
      - "127.0.0.1:1880:1880"
    environment:
      - TZ=Europe/Istanbul
      - NODE_RED_CREDENTIAL_SECRET=${NODE_RED_CREDENTIAL_SECRET}
    volumes:
      - ./data:/data

# .env  (misma carpeta, nunca subas este archivo al repositorio)
NODE_RED_CREDENTIAL_SECRET=change-me-to-a-long-random-string

mkdir -p data && sudo chown -R 1000:1000 data
docker compose up -d

Merece la pena destacar dos detalles. Primero, el puerto se publica solo en 127.0.0.1, de modo que el editor es accesible desde el host pero no desde la red. Pon delante un proxy inverso con HTTPS si necesitas acceso remoto, y lee cómo asegurar Node-RED antes de exponerlo. Segundo, el secreto de credenciales se lee del entorno. Edita data/settings.js y define:

// data/settings.js
credentialSecret: process.env.NODE_RED_CREDENTIAL_SECRET,

Esta clave cifra flows_cred.json. Si no la defines, Node-RED genera una clave y la guarda dentro de la carpeta de datos, lo que funciona pero ata tus credenciales a esa copia concreta. Con un secreto explícito puedes reconstruir el contenedor en cualquier lugar y seguir descifrando las contraseñas de tu broker.

Instalar nodos adicionales en el contenedor

Usa Manage palette en el editor como de costumbre; los nodos se instalan en /data/node_modules y sobreviven a la recreación del contenedor porque /data es un volumen. Para automatizarlo con un script:

docker exec -it nodered bash -c "cd /data && npm install @flowfuse/node-red-dashboard"
docker restart nodered

Para imágenes totalmente reproducibles, crea tu propia imagen que instale los nodos en tiempo de compilación:

# Dockerfile
FROM nodered/node-red:4.0.9
RUN npm install --no-audit --no-fund @flowfuse/node-red-dashboard node-red-contrib-modbus

Los nodos que compilan código nativo pueden necesitar herramientas de compilación; la documentación de la imagen en nodered.org explica las variantes disponibles y cómo añadirlas.

Conecta el contenedor a un broker MQTT

Un error frecuente con Node-RED en Docker es apuntar el nodo MQTT a localhost. Dentro del contenedor, localhost es el propio contenedor, no tu host. Usa un nombre de host real: un broker en la nube, un nombre de servicio en la misma red de Compose o host.docker.internal en Docker Desktop.

Para una primera prueba, usa el servidor MQTT público gratuito. En el nodo de configuración del broker, indica el servidor broker.connectmq.com, el puerto 1883 y un client ID único como nr-docker-4d2f. Suscríbete a connectmq/demo/4d2f/# y publica desde tu host:

mosquitto_pub -h broker.connectmq.com -p 1883 -i demo-host-4d2f \
  -t "connectmq/demo/4d2f/docker/test" -m '{"hello":"from host"}'

En producción, cambia a tu broker privado con TLS. Indica como servidor el host de tu broker de ConnectMQ, el puerto 8883, marca Use TLS y rellena el usuario, la contraseña y el client ID del portal. Como la imagen incluye los certificados de CA estándar, el certificado de Let's Encrypt es de confianza sin configuración adicional. El recorrido completo de TLS está en Node-RED MQTT TLS.

Solo escribes esas credenciales una vez en el editor. Node-RED las guarda en flows_cred.json, cifradas con el secreto de credenciales que definiste antes, nunca en texto plano dentro de flows.json, así que puedes compartir o subir al repositorio el archivo de flujo sin filtrar la contraseña de tu broker.

Lista de actualizaciones y copias de seguridad

1. Haz una copia de seguridad de la carpeta o el volumen de datos antes de cada actualización.
2. Cambia la etiqueta de la imagen en docker-compose.yml y ejecuta docker compose pull && docker compose up -d.
3. Vigila docker logs -f nodered por si algún nodo no se carga tras la actualización.
4. Si es necesario, vuelve atrás restaurando la etiqueta anterior; la carpeta de datos no cambia.
5. Recompila los nodos con código nativo tras un cambio de versión mayor de Node.js (npm rebuild dentro de /data).
6. Mantén .env fuera del control de versiones y guárdalo en tu gestor de secretos.
7. Prueba restauraciones de vez en cuando; una copia de seguridad que nunca has restaurado es una suposición.

Si el nodo MQTT muestra "connecting" tras cualquiera de estos pasos, la guía Node-RED MQTT no conecta repasa los problemas de DNS, puertos, TLS y client ID que son habituales en contenedores.

Ejecuta tu Node-RED en Docker con ConnectMQ

Los contenedores se encargan de Node-RED; un broker MQTT gestionado se encarga de la capa de mensajería para que no tengas que ejecutar y parchear también un contenedor de broker. ConnectMQ ofrece TCP 1883, TLS 8883 y WebSocket seguro 8084, MQTT 3.1.1 y 5.0, y un portal con un explorador de topics en directo para comprobar lo que publica tu contenedor. Regístrate en app.connectmq.com para obtener el plan Serverless gratuito, sin tarjeta de crédito, y pega las credenciales generadas en el nodo broker. Para una visión más amplia de las opciones de alojamiento, consulta nuestra guía de broker MQTT en la nube, y el tutorial de Node-RED MQTT para crear tus primeros flujos.

Preguntas frecuentes

¿Dónde guarda Node-RED los datos en Docker?

Todo, incluidos los flujos, las credenciales, settings.js, el contexto y los nodos instalados, vive en /data dentro del contenedor. Móntalo como volumen o bind mount para que sobreviva a la recreación del contenedor.

¿Por qué mi contenedor de Node-RED no puede conectarse a un broker MQTT en localhost?

Dentro de un contenedor, localhost se refiere al propio contenedor. Usa el nombre de host real del broker, un nombre de servicio de Compose o host.docker.internal en Docker Desktop.

¿Cómo soluciono los errores de permiso denegado con un bind mount?

El contenedor ejecuta Node-RED con el UID 1000. Cambia el propietario de la carpeta del host con sudo chown -R 1000:1000 <folder> y reinicia el contenedor.

¿Puedo ejecutar Node-RED en Docker en una Raspberry Pi?

Sí. La imagen oficial se publica para arquitecturas ARM, así que los mismos comandos y el mismo archivo Compose funcionan en una Raspberry Pi con un sistema operativo compatible.