Como Instalar o Node-RED no Windows, Linux e Raspberry Pi

Você consegue instalar o Node-RED em poucos minutos em praticamente qualquer máquina, de um notebook Windows a um Raspberry Pi na prateleira de uma fábrica. Este guia percorre cada plataforma, mostra como rodar o Node-RED como serviço, protege o editor e termina com um primeiro fluxo funcionando, que assina um broker MQTT ao vivo para você ver mensagens reais chegando.

O que você precisa antes de começar

O Node-RED é uma aplicação Node.js, então o único pré-requisito de verdade é uma versão suportada do Node.js. O Node-RED 4.x exige Node.js 18 ou superior, e versões futuras podem elevar esse mínimo, então use a versão LTS atual do Node.js sempre que possível. Você também precisa de:

• Uma conta de usuário com permissão para instalar software (administrador no Windows, sudo no Linux).
• Acesso de rede ao npm (o registro de pacotes do Node.js) durante a instalação.
• Um navegador para abrir o editor na porta 1880.

Instalar o Node-RED no Windows

1. Baixe o instalador LTS do Node.js (.msi) em nodejs.org e execute-o com as opções padrão. Aceite a opção que adiciona o Node.js ao PATH.
2. Abra uma nova janela do PowerShell e confira as versões:

node --version
npm --version

3. Instale o Node-RED globalmente:

npm install -g --unsafe-perm node-red

4. Inicie-o:

node-red

O log termina com uma linha como Server now running at http://127.0.0.1:1880/. Abra esse endereço no navegador e o editor aparece. Seus fluxos e configurações ficam em C:\Users\<você>\.node-red.

Para manter o Node-RED rodando depois de fechar o terminal e iniciá-lo no boot, uma abordagem comum é o PM2:

npm install -g pm2
pm2 start "$env:APPDATA\npm\node_modules\node-red\red.js" --name node-red
pm2 save

No Windows, o PM2 precisa de um auxiliar extra, como o pm2-installer ou um wrapper de serviço do Windows, para iniciar no boot; siga as instruções dele ou use o Agendador de Tarefas para executar pm2 resurrect no logon.

Instalar o Node-RED no Linux e no Raspberry Pi

No Debian, Ubuntu e Raspberry Pi OS, o projeto Node-RED fornece um script de instalação que instala uma versão adequada do Node.js, instala o Node-RED e configura um serviço systemd. Execute-o como usuário comum com permissão de sudo, não como root:

bash <(curl -sL https://github.com/node-red/linux-installers/releases/latest/download/update-nodejs-and-nodered-deb)

O script faz algumas perguntas, como se deve substituir uma instalação existente do Node.js e se deve instalar os nodes específicos do Pi. Ao terminar, inicie o Node-RED e habilite-o no boot:

node-red-start                      # inicia o serviço e acompanha o log
sudo systemctl enable nodered.service

Comandos úteis depois disso:

node-red-stop
node-red-restart
node-red-log

Em seguida, acesse http://<ip-do-dispositivo>:1880. Para descobrir o endereço do Pi, execute hostname -I. O mesmo script é a forma mais fácil de atualizar depois: execute-o de novo e ele atualiza o Node.js e o Node-RED no lugar. Todos os detalhes e opções estão na documentação oficial de primeiros passos do Node-RED.

Em outras distribuições, instale o Node.js LTS pelo gerenciador de pacotes ou pelo NodeSource, execute sudo npm install -g --unsafe-perm node-red e crie sua própria unit do systemd.

Instalar o Node-RED com Docker

Se você já usa contêineres, o Docker é a opção mais limpa, porque atualizações e rollbacks são apenas tags de imagem:

docker volume create node_red_data
docker run -d --name nodered --restart unless-stopped \
  -p 1880:1880 -v node_red_data:/data nodered/node-red:latest

O volume /data guarda seus fluxos, credenciais e nodes instalados, de modo que eles sobrevivem às atualizações do contêiner. Para fixar uma versão, troque latest por uma tag específica. Nosso guia de Node-RED com Docker cobre Docker Compose, variáveis de ambiente e backups.

Proteja o editor antes de expô-lo

Por padrão, o editor não tem login. Isso não é problema em 127.0.0.1, mas em um Raspberry Pi ou servidor qualquer pessoa na rede pode abrir a porta 1880 e executar código arbitrário por meio de um node Function ou Exec. Antes de usar o Node-RED em uma rede compartilhada:

1. Gere um hash de senha:

node-red admin hash-pw

2. Edite o settings.js no seu diretório de usuário (~/.node-red/settings.js) e habilite o adminAuth:

adminAuth: {
    type: "credentials",
    users: [{
        username: "admin",
        password: "PASTE_THE_BCRYPT_HASH_HERE",
        permissions: "*"
    }]
},

3. Defina um credentialSecret no mesmo arquivo para que as credenciais armazenadas sejam criptografadas com uma chave que você controla e reinicie o Node-RED.

Para HTTPS, proxies reversos e mais medidas de hardening, veja como proteger o Node-RED.

Seu primeiro fluxo MQTT depois de instalar o Node-RED

Agora conecte o Node-RED a um broker real. O servidor MQTT público em broker.connectmq.com aceita conexões anônimas, então você pode testar sem criar conta. Use um prefixo de topic exclusivo e lembre-se de que a área pública é visível para todos.

No editor, abra o menu (canto superior direito), escolha Import, cole o JSON abaixo e clique em Import:

[
  {
    "id": "c0a1b2c3d4e5f601",
    "type": "mqtt-broker",
    "name": "ConnectMQ public",
    "broker": "broker.connectmq.com",
    "port": "1883",
    "clientid": "nodered-first-4d9e",
    "autoConnect": true,
    "usetls": false,
    "protocolVersion": "4",
    "keepalive": "60",
    "cleansession": true,
    "autoUnsubscribe": true
  },
  {
    "id": "c0a1b2c3d4e5f602",
    "type": "inject",
    "name": "Send test reading",
    "props": [{ "p": "payload" }, { "p": "topic", "vt": "str" }],
    "repeat": "",
    "once": false,
    "topic": "connectmq/demo/4d9e/sensor",
    "payload": "{\"temperature\":21.5}",
    "payloadType": "json",
    "x": 160,
    "y": 80,
    "wires": [["c0a1b2c3d4e5f603"]]
  },
  {
    "id": "c0a1b2c3d4e5f603",
    "type": "mqtt out",
    "name": "Publish",
    "topic": "",
    "qos": "0",
    "retain": "false",
    "broker": "c0a1b2c3d4e5f601",
    "x": 380,
    "y": 80,
    "wires": []
  },
  {
    "id": "c0a1b2c3d4e5f604",
    "type": "mqtt in",
    "name": "Subscribe demo topics",
    "topic": "connectmq/demo/4d9e/#",
    "qos": "0",
    "datatype": "auto-detect",
    "broker": "c0a1b2c3d4e5f601",
    "nl": false,
    "rap": true,
    "rh": 0,
    "inputs": 0,
    "x": 180,
    "y": 160,
    "wires": [["c0a1b2c3d4e5f605"]]
  },
  {
    "id": "c0a1b2c3d4e5f605",
    "type": "debug",
    "name": "Show message",
    "active": true,
    "tosidebar": true,
    "console": false,
    "complete": "true",
    "targetType": "full",
    "x": 410,
    "y": 160,
    "wires": []
  }
]

Substitua 4d9e por caracteres aleatórios seus no client ID e nos dois topics e clique em Deploy. Os nodes MQTT mostram o status verde "connected". Clique no botão do node inject e a barra lateral de debug mostra a mensagem completa, com o payload já convertido em objeto graças à configuração de autodetecção. Você também pode publicar a partir de outra ferramenta, como mosquitto_pub -h broker.connectmq.com -p 1883 -i cli-4d9e -t connectmq/demo/4d9e/cli -m hello, e ver a mensagem chegar.

A partir daqui, o tutorial de MQTT no Node-RED aborda topics, QoS, tratamento de JSON e dashboards em profundidade.

Solução de problemas na instalação

• node-red não é reconhecido (Windows): feche e abra o PowerShell de novo para carregar o PATH atualizado ou verifique se %APPDATA%\npm está no PATH.
• Porta 1880 já em uso: outra instância está rodando. Pare-a ou inicie com node-red -p 1881.
• Editor inacessível a partir de outra máquina: verifique o firewall e confirme que o Node-RED não está vinculado apenas ao localhost por meio do uiHost no settings.js.
• Nodes MQTT presos em "connecting": verifique o acesso de saída à porta 1883 e garanta que o client ID não esteja vazio nem em uso por outro cliente. Nosso guia Node-RED MQTT não conecta lista mais causas.
• Script de instalação falha em um Pi antigo: modelos muito antigos com CPUs ARMv6 podem não ser suportados pelas builds atuais do Node.js; confira a saída do instalador para orientações.

Do servidor MQTT público para a produção

O servidor MQTT público é perfeito para um primeiro fluxo, mas fluxos de produção precisam de credenciais privadas e criptografia. Passe para a porta 8883 com TLS, o que se resume a uma caixa de seleção e alguns campos no node de configuração do broker; nosso guia de Node-RED MQTT com TLS mostra o passo a passo. Rodar o broker por conta própria significa aplicar patches, cuidar de certificados e planejar capacidade, e é por isso que muitas equipes combinam o Node-RED com um broker MQTT gerenciado, por exemplo para coletar dados de um Raspberry Pi numa fazenda ou numa estação de saneamento sem manter servidor próprio. O ConnectMQ oferece ao Node-RED um broker privado com TLS na 8883, credenciais geradas no portal e um explorador de topics ao vivo para conferir o que seus fluxos publicam. Para uma visão mais ampla, veja nosso guia de broker MQTT na nuvem.

Rode seus fluxos Node-RED no ConnectMQ

Cadastre-se em app.connectmq.com, escolha o plano Serverless gratuito, sem cartão de crédito, crie um broker e cole o username, a senha e o client ID gerados no seu node de configuração mqtt-broker. Pronto: sua nova instalação do Node-RED está conectada a um broker ConnectMQ privado e criptografado.

Perguntas frequentes

Qual versão do Node.js preciso para o Node-RED?

O Node-RED 4.x exige Node.js 18 ou superior. Use a versão LTS atual do Node.js, a menos que sua plataforma tenha alguma restrição específica.

Onde o Node-RED guarda meus fluxos?

No diretório de usuário, por padrão ~/.node-red no Linux e macOS e C:\Users\<você>\.node-red no Windows, ou /data dentro do contêiner Docker. Faça backup dessa pasta, incluindo o flows_cred.json.

Como atualizo o Node-RED?

No Debian, Ubuntu e Raspberry Pi OS, execute o script de instalação novamente. Com npm, execute npm install -g --unsafe-perm node-red. Com Docker, baixe uma imagem mais nova e recrie o contêiner com o mesmo volume.

Posso instalar o Node-RED sem acesso à internet?

Sim, mas você precisa baixar antes o Node.js e os pacotes npm em outra máquina e transferi-los, ou montar uma imagem Docker em outro lugar e carregá-la. Conectar-se a um broker na nuvem depois, claro, exige acesso de rede de saída.