Self-Hosting Node-RED

What Is Node-RED?

Node-RED is an open-source, flow-based programming tool originally created by IBM and now maintained by the OpenJS Foundation. It runs as a lightweight Node.js application and provides a browser-based visual editor that lets you wire together hardware devices, APIs, databases, and online services by connecting nodes on a canvas.

Unlike traditional programming, Node-RED does not require writing extensive code for most integrations. You drag nodes from the palette, drop them on the canvas, connect them with wires, and click Deploy. The underlying runtime handles the messaging and execution. When you do need custom logic, JavaScript function nodes let you write code inline.

Why Self-Host Node-RED?

Cloud-hosted Node-RED services exist (FlowFuse, IBM Cloud), but self-hosting gives you advantages that matter in real projects:

Prerequisites

Node-RED requires Node.js v18 or higher. Check your current version:

$ node --version
v20.11.0
$ npm --version
10.2.4

node --version   # Must be v18 or higher
npm --version

If Node.js is not installed or is outdated, install it for your platform:

# Windows / macOS:
# Download the LTS version from https://nodejs.org

# Ubuntu / Debian:
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Raspberry Pi OS (Bookworm):
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# macOS via Homebrew:
brew install node@20

Installation Method 1: npm (Windows, macOS, Linux)

The simplest way to install Node-RED on any system with Node.js is via npm:

added 329 packages in 45s

# Global installation (recommended for most users):
npm install -g --unsafe-perm node-red

# Verify installation:
node-red --version

The --unsafe-perm flag is required on some systems to allow native module compilation during installation. After installation, verify the version:

$ node-red --version
v4.0.9

node-red

Welcome to Node-RED
===================

30 Jan 12:00:00 - [info] Node-RED version: v4.0.9
30 Jan 12:00:00 - [info] Node.js  version: v20.11.0
30 Jan 12:00:00 - [info] Loading palette nodes
30 Jan 12:00:00 - [info] Server now running at http://127.0.0.1:1880/
30 Jan 12:00:00 - [info] Starting flows
30 Jan 12:00:00 - [info] Started flows

Installation Method 2: Raspberry Pi (Official Script)

Node-RED provides an official install script for Raspberry Pi OS and other Debian-based Linux systems. This script installs Node.js, npm, Node-RED, and sets up a systemd service for automatic startup in one command:

Running Node-RED install for user pi at /home/pi on raspbian
...
This can take 20-30 minutes on the slower Pi versions - please wait.
...
All done. You can now start Node-RED with the command  node-red-start
or using the icon under   Menu / Programming / Node-RED
To run Node-RED in the background and start on every boot:
  sudo systemctl enable nodered.service

bash <(curl -sL https://raw.githubusercontent.com/node-red/linux-installers/master/deb/update-nodejs-and-nodered)

The script asks if you want to install the Pi-specific nodes and whether to start Node-RED on boot. After installation, use these commands to manage the service:

# Start Node-RED:
node-red-start

# Stop Node-RED:
node-red-stop

# View logs:
node-red-log

# Enable autostart on boot:
sudo systemctl enable nodered

# Disable autostart:
sudo systemctl disable nodered

Installation Method 3: Docker

Docker is the recommended installation method for production self-hosting because it isolates Node-RED from the host system, makes upgrades trivial, and ensures consistent behavior across machines.

Unable to find image 'nodered/node-red:latest' locally
latest: Pulling from nodered/node-red
...
Status: Downloaded newer image for nodered/node-red:latest

Welcome to Node-RED
===================
30 Jan 12:00:00 - [info] Server now running at http://127.0.0.1:1880/

Quick start with Docker:

docker run -it -p 1880:1880 -v node_red_data:/data --name mynodered nodered/node-red:latest

This command starts Node-RED with persistent storage. The -v node_red_data:/data flag creates a named volume to store your flows, credentials, and installed nodes. Without it, everything is lost when the container stops.

Recommended: Docker Compose

For a production setup with automatic restarts, create a docker-compose.yml file:

version: "3.8"
services:
  node-red:
    image: nodered/node-red:latest
    container_name: node-red
    restart: unless-stopped
    ports:
      - "1880:1880"
    volumes:
      - ./node-red-data:/data
    environment:
      - TZ=Europe/Istanbul          # Set your timezone
      - NODE_RED_ENABLE_PROJECTS=true  # Enable Git-backed projects

# Start:
docker compose up -d

# View logs:
docker compose logs -f node-red

# Stop:
docker compose down

# Update to latest version:
docker compose pull && docker compose up -d

Installation Method 4: Windows

On Windows, install Node.js from nodejs.org (LTS version), then open Command Prompt or PowerShell as Administrator and run:

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

Node-RED stores its data (flows, credentials, settings) in C:\Users\<username>\.node-red\. To run Node-RED automatically on Windows startup, use the Task Scheduler or install it as a Windows service using the node-windows package.

Securing Node-RED Before Exposing It to the Internet

Step 1: Generate a password hash

Node-RED stores passwords as bcrypt hashes, not plain text. Generate the hash using the built-in tool:

$ node-red admin hash-pw
Password: ********
$2b$08$AbCdEfGhIjKlMnOpQrStUuVwXyZ012345678901234567890

node-red admin hash-pw

Enter your desired password when prompted. Copy the output hash, which looks like $2b$08$....

Step 2: Edit settings.js

The Node-RED settings file is located at:

Open settings.js in a text editor and find the adminAuth section. It is commented out by default. Uncomment it and fill in your username and the hash you generated:

adminAuth: {
    type: "credentials",
    users: [
        {
            username: "admin",
            password: "$2b$08$YOUR_GENERATED_HASH_HERE",
            permissions: "*"
        },
        {
            username: "viewer",
            password: "$2b$08$VIEWER_HASH_HERE",
            permissions: "read"   // read-only access
        }
    ]
},

Step 3: Protect the Dashboard (httpNodeAuth)

adminAuth only protects the flow editor. The Node-RED Dashboard and HTTP-In nodes are on a separate route and need their own authentication:

httpNodeAuth: {
    user: "user",
    pass: "$2b$08$YOUR_HASH_HERE"
},

Step 4: Restart Node-RED

# npm install (Linux/macOS):
node-red-stop && node-red-start

# Raspberry Pi service:
node-red-stop && node-red-start

# Docker Compose:
docker compose restart node-red

# systemd:
sudo systemctl restart nodered

After restart, visiting http://localhost:1880 shows a login screen.

Running Node-RED as a System Service (Auto-Start on Boot)

Running Node-RED manually means it stops when you close the terminal or reboot. For a proper self-hosted setup, Node-RED should run as a background service that starts automatically.

# If you used the Raspberry Pi install script, systemd is already configured:
sudo systemctl enable nodered   # Enable autostart
sudo systemctl start nodered    # Start now
sudo systemctl status nodered   # Check status

# If installing manually on Debian/Ubuntu, use the official install script which
# sets up the systemd service file automatically:
bash <(curl -sL https://raw.githubusercontent.com/node-red/linux-installers/master/deb/update-nodejs-and-nodered)

# Install PM2:
npm install -g pm2

# Start Node-RED with PM2:
pm2 start node-red -- --max-old-space-size=256

# Save the process list and generate startup script:
pm2 save
pm2 startup   # Follow the printed command to enable autostart

# Useful PM2 commands:
pm2 list          # Show all processes
pm2 logs node-red # View Node-RED logs
pm2 restart node-red
pm2 stop node-red

# Enable Docker to start on boot (Linux):
sudo systemctl enable docker

Receiving Webhooks in Node-RED

One of the most powerful use cases for self-hosted Node-RED is receiving webhooks from external services: GitHub, Stripe, Twilio, Slack, Shopify, or any service that sends HTTP POST requests on events. This requires Node-RED to be accessible from the internet via a public URL.

Remote Access: Expose Node-RED to the Internet with Localtonet

Localtonet creates an encrypted tunnel from your local machine to a public HTTPS endpoint. When someone (or a webhook sender) accesses the public URL, the request is forwarded through the tunnel to your Node-RED instance running on localhost:1880. No port forwarding, no static IP, and it works behind NAT and CGNAT.

# macOS:
brew tap localtonet/tap && brew install localtonet

# Linux / Raspberry Pi:
curl -fsSL https://localtonet.com/install.sh | sh

# Windows:
# Download the installer from localtonet.com/download

localtonet --authtoken YOUR_TOKEN_HERE

Run Localtonet as a Service (Always-On Tunnel)

For a persistent setup where the tunnel automatically restarts on reboot alongside Node-RED, run Localtonet as a system service:

# Install and start as a service (Linux / Raspberry Pi):
sudo localtonet --install-service --authtoken YOUR_TOKEN_HERE
sudo localtonet --start-service --authtoken YOUR_TOKEN_HERE

# Check service status:
sudo localtonet --status-service

# Stop service:
sudo localtonet --stop-service

What You Can Build with Self-Hosted Node-RED + Localtonet

Troubleshooting Common Issues

Frequently Asked Questions