Node-RED no Docker para Projetos MQTT

Rodar o Node-RED no Docker oferece uma instalação reproduzível, fácil de atualizar, fazer backup e mover entre máquinas. Neste tutorial você vai iniciar a imagem Docker oficial do Node-RED, manter seus fluxos em um volume persistente, gerenciá-lo com Docker Compose, adicionar nodes extras, passar segredos com segurança e conectar o contêiner a um broker MQTT via TLS.

Por que rodar o Node-RED no Docker

Instalar o Node-RED diretamente com npm funciona bem, e nosso guia para instalar o Node-RED cobre esse caminho. Os contêineres trazem algumas vantagens que fazem diferença quando um fluxo passa a fazer trabalho de verdade:

Versões fixas. Você escolhe a versão exata do Node-RED e do Node.js pela tag da imagem, então uma atualização é uma mudança deliberada.
Separação limpa. Tudo o que o Node-RED grava fica em um diretório, /data, que você monta como volume. Faça backup dessa pasta e você tem tudo.
Rollback fácil. Se uma atualização quebrar um node da comunidade, volte para a tag anterior.
Mesma configuração em todo lugar. Um arquivo Compose roda de forma idêntica em um notebook, em um Raspberry Pi com SO de 64 bits ou em uma VM na nuvem.

A imagem oficial é a nodered/node-red no Docker Hub. Tags como latest, uma versão específica como 4.0.9 ou variantes com determinada versão do Node.js permitem escolher o quanto fixar. Em produção, fixe uma tag de versão em vez de latest.

Início rápido com docker run

Garanta que o Docker esteja instalado e execute:

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

Abra http://localhost:1880 e você tem um editor funcionando. A flag importante é -v node_red_data:/data. Sem ela, fluxos, nodes instalados e credenciais ficam na camada gravável do contêiner e desaparecem quando você remove ou recria o contêiner. TZ define o fuso horário (no Brasil, por exemplo, America/Sao_Paulo) para que timestamps e agendamentos de inject correspondam ao seu horário local.

Comandos úteis no dia a dia:

docker logs -f nodered          # acompanha o log do Node-RED
docker exec -it nodered bash    # shell dentro do contêiner
docker restart nodered          # reinicia depois de editar o settings.js

A política --restart unless-stopped traz o Node-RED de volta automaticamente após uma falha ou reinicialização do host, mas não depois que você o para deliberadamente. Isso importa para fluxos MQTT: quando o contêiner reinicia, o node do broker se reconecta sozinho e as assinaturas são restauradas a partir do fluxo, de modo que um gateway em uma fazenda ou subestação que fica sem energia se recupera sem ninguém mexer nele. Combine isso com armazenamento persistente, descrito a seguir, para que os fluxos com que ele reinicia sejam os que você implantou.

Volume nomeado ou bind mount

Você pode montar um volume nomeado, como acima, ou uma pasta do 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

Um bind mount facilita editar e fazer backup do settings.js e do flows.json a partir do host. O porém são as permissões: o contêiner roda o Node-RED como um usuário com UID 1000. Se a pasta do host pertencer ao root ou a outro usuário, o Node-RED não consegue gravar e você verá erros EACCES no log. O chown acima evita isso.

	Volume nomeado	Bind mount
Configuração	Nada a preparar	A pasta precisa ser gravável pelo UID 1000
Editar o settings.js	Via `docker exec` ou um contêiner auxiliar	Direto no host
Backups	`docker run --rm -v node_red_data:/data ...` com tar	Qualquer ferramenta de backup de arquivos
Portabilidade	Gerenciado pelo Docker	Caminho visível no host

Um arquivo Docker Compose pronto para produção

Para qualquer coisa de longa duração, descreva o contêiner no Compose. Este arquivo fixa a imagem, persiste os dados, define o fuso horário e passa segredos por um arquivo de ambiente:

# 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  (mesma pasta, nunca faça commit deste arquivo)
NODE_RED_CREDENTIAL_SECRET=change-me-to-a-long-random-string

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

Vale destacar dois detalhes. Primeiro, a porta é publicada apenas em 127.0.0.1, então o editor é acessível a partir do host, mas não pela rede. Coloque um proxy reverso com HTTPS na frente se precisar de acesso remoto e leia como proteger o Node-RED antes de expô-lo. Segundo, o segredo de credenciais é lido do ambiente. Edite o data/settings.js e defina:

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

Essa chave criptografa o flows_cred.json. Se você não a definir, o Node-RED gera uma chave e a guarda dentro da pasta de dados, o que funciona, mas amarra suas credenciais àquela única cópia. Com um segredo explícito, você pode recriar o contêiner em qualquer lugar e ainda descriptografar as senhas do broker.

Instalando nodes extras no contêiner

Use o Manage palette no editor, como de costume; os nodes são instalados em /data/node_modules e sobrevivem à recriação do contêiner porque /data é um volume. Para fazer isso por script:

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

Para imagens totalmente reproduzíveis, crie sua própria imagem que instala os nodes no momento do build:

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

Nodes que compilam código nativo podem precisar de ferramentas de build; a documentação da imagem em nodered.org explica as variantes disponíveis e como adicioná-las.

Conecte o contêiner a um broker MQTT

Um erro frequente com Node-RED no Docker é apontar o node MQTT para localhost. Dentro do contêiner, localhost é o próprio contêiner, não o seu host. Use um hostname real: um broker na nuvem, um nome de serviço na mesma rede do Compose ou host.docker.internal no Docker Desktop.

Para um primeiro teste, use o servidor MQTT público (gratuito), que serve apenas para testes e protótipos. No node de configuração do broker, defina o servidor broker.connectmq.com, a porta 1883 e um client ID exclusivo, como nr-docker-4d2f. Assine connectmq/demo/4d2f/# e publique a partir do host:

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

Para produção, passe para o seu broker privado com TLS. Defina o servidor como o host do seu broker ConnectMQ, a porta 8883, marque Use TLS e preencha o username, a senha e o client ID do portal. Como a imagem inclui os certificados de CA padrão, o certificado Let's Encrypt é confiável sem configuração extra. O passo a passo completo de TLS está em Node-RED MQTT com TLS.

Você digita essas credenciais apenas uma vez no editor. O Node-RED as guarda em flows_cred.json, criptografadas com o segredo de credenciais definido acima, nunca em texto puro dentro do flows.json, então você pode compartilhar ou versionar o arquivo de fluxo sem vazar a senha do broker.

Checklist de atualizações e backups

Faça backup da pasta ou do volume de dados antes de cada atualização.
Altere a tag da imagem no docker-compose.yml e execute docker compose pull && docker compose up -d.
Acompanhe docker logs -f nodered em busca de nodes que falhem ao carregar após a atualização.
Se necessário, faça rollback restaurando a tag anterior; a pasta de dados não muda.
Recompile os nodes com código nativo após uma mudança de versão principal do Node.js (npm rebuild dentro de /data).
Mantenha o .env fora do controle de versão e guarde-o no seu gerenciador de segredos.
Teste restaurações de vez em quando; um backup que você nunca restaurou é um palpite.

Se o node MQTT mostrar "connecting" depois de qualquer um desses passos, o guia Node-RED MQTT não conecta percorre problemas de DNS, portas, TLS e client ID comuns em contêineres.

Rode seu Node-RED em Docker com o ConnectMQ

Os contêineres cuidam do Node-RED; um broker MQTT gerenciado cuida da camada de mensageria, para que você não precise também rodar e atualizar um contêiner de broker. O ConnectMQ oferece TCP 1883, TLS 8883 e WebSocket seguro 8084, MQTT 3.1.1 e 5.0 e um portal com explorador de topics ao vivo para conferir o que o seu contêiner publica. Cadastre-se em app.connectmq.com no plano Serverless (Free), sem cartão de crédito, e cole as credenciais geradas no node do broker. Para uma visão mais ampla das opções de hospedagem, veja nosso guia de broker MQTT na nuvem e o tutorial de MQTT no Node-RED para montar seus primeiros fluxos.

Perguntas frequentes

Onde o Node-RED guarda os dados no Docker?

Tudo, incluindo fluxos, credenciais, settings.js, contexto e nodes instalados, fica em /data dentro do contêiner. Monte-o como volume ou bind mount para que sobreviva à recriação do contêiner.

Por que meu contêiner Node-RED não consegue se conectar a um broker MQTT em localhost?

Dentro de um contêiner, localhost se refere ao próprio contêiner. Use o hostname real do broker, um nome de serviço do Compose ou host.docker.internal no Docker Desktop.

Como corrijo erros de permission denied com bind mount?

O contêiner roda o Node-RED como UID 1000. Altere o dono da pasta do host com sudo chown -R 1000:1000 <pasta> e reinicie o contêiner.

Posso rodar o Node-RED no Docker em um Raspberry Pi?

Sim. A imagem oficial é publicada para arquiteturas ARM, então os mesmos comandos e o mesmo arquivo Compose funcionam em um Raspberry Pi com um SO suportado.

Como Rodar o Node-RED no Docker em Projetos MQTT