Node-RED

Overview

Node-RED lets you assemble automation as a flow of visible nodes. An incoming webhook, timer, MQTT message, HTTP request, database query, or a small JavaScript function can feed the next step. It is especially useful for smart home and device work, but it also makes a compact self-hosted alternative for API glue and scheduled jobs.

This recipe runs one official Node-RED container with no database. Its persistent volume holds flows, installed nodes, settings, and encrypted credentials. The editor requires a locally configured password and is bound to localhost by default; put it behind one of the supplied HTTPS reverse-proxy examples before making it public.

Node-RED is a better fit than n8n when you want direct control of event and IoT flows, custom JavaScript, and a small runtime. n8n has more ready-made SaaS connectors and a more guided execution history. Neither product makes an unreviewed community node safe: review packages before installing them.

Security assessment

This recipe does not use privileged mode, host networking, or the Docker socket, and applies no-new-privileges. The editor is bound to 127.0.0.1 by default, so it is not directly reachable from the network.

The editor is nevertheless a high-trust control plane. Anyone with editor credentials can deploy arbitrary JavaScript through Function nodes and install third-party palette packages; both run with the container’s permissions. Give editor access only to people who are allowed to run code on the server, and review community nodes before installing them.

Flows can hold API tokens and passwords. They are encrypted with NODE_RED_CREDENTIAL_SECRET, but an attacker who obtains both that secret and the persistent volume or backup can decrypt them. Treat .env and backups as password-equivalent secrets. If you publish the editor or webhooks, place them behind HTTPS, use a unique strong password, and avoid exposing port 1880 directly.

Step-by-step guide

1. Check the server

Use Ubuntu 22.04+ or Debian 12+ with Docker Engine and Docker Compose v2.24+. Node-RED needs 1 CPU, 256 MB RAM, and 2 GB of disk at minimum; reserve 512 MB when flows use many nodes or keep sizeable context. This recipe has no separate database: flows, installed nodes, and credentials live in a Docker volume.

docker --version
docker compose version

2. Prepare the recipe

Place all recipe files in a private directory, including config/settings.js:

mkdir -p ~/services/node-red
cd ~/services/node-red
cp .env.example .env
chmod 600 .env

Generate a bcrypt editor-password hash and a credential-encryption secret. Put the hash, not the plain password, in .env; save the plain password and the secret in a password manager. Never change NODE_RED_CREDENTIAL_SECRET after creating credentials, or existing ones will no longer decrypt.

docker run --rm -it nodered/node-red:5.0.8-24 node-red admin hash-pw
openssl rand -hex 32

Set the first output as NODE_RED_ADMIN_PASSWORD_HASH, choose a non-default NODE_RED_ADMIN_USERNAME, and set the second as NODE_RED_CREDENTIAL_SECRET. NODE_RED_SETTINGS_FILE is the supplied JavaScript settings file; it enables password login and must remain readable to the container.

3. Start Node-RED

docker compose pull
docker compose up -d
docker compose ps
curl -I http://127.0.0.1:1880/

The last command returns an HTTP response, but the editor must ask for the credentials configured above. First sign in through an SSH tunnel:

ssh -L 1880:127.0.0.1:1880 user@server.example

Open http://localhost:1880, sign in, drag an Inject node and a Debug node onto a new flow, connect them, then click Deploy. This confirms that the editor can save and run a flow. Do not put real tokens in an unencrypted export or screenshot.

Local network

Keep the localhost bind and use the SSH tunnel where possible. To expose it to a trusted LAN, replace 127.0.0.1 in the port mapping with the server’s LAN IP (for example 192.168.1.10) and firewall port 1880 from every other network. Never bind the unauthenticated port to all interfaces; password login is not a replacement for TLS or network access control.

Domain and HTTPS

The proxy/ directory contains Caddy, Nginx, and Traefik examples for flows.example.com. Replace it with your name. Caddy requests TLS automatically; Nginx expects existing Certbot certificates; Traefik uses a resolver called letsencrypt. Forward Host, X-Forwarded-For, and X-Forwarded-Proto unchanged if adapting an example. Sign in through the HTTPS address before publishing any webhook endpoint.

Backup

chmod +x backup.sh restore.sh
./backup.sh

The script stops Node-RED briefly and archives its complete data volume. That includes flows, installed palette modules, and encrypted credentials. Copy the archive off the server encrypted; keep the .env credential secret and the recipe’s config/settings.js with it, but separately protected.

Restore

Restore irreversibly replaces the current data volume. The script creates a safety backup first, then restores the selected archive:

./restore.sh ./backups/node-red-YYYYMMDDTHHMMSSZ.tar.gz
docker compose up -d

Open the editor and deploy a harmless saved flow. Use the same NODE_RED_CREDENTIAL_SECRET from the time of the backup; without it, encrypted credentials cannot be used.

Update

Back up first, read the release notes, change NODE_RED_VERSION in .env, and recreate the service:

docker compose pull
docker compose up -d
docker compose logs --tail=100 node-red

Sign in and deploy a small existing flow. Review release notes before changing the Node.js variant (-24) or installed third-party nodes.

Rollback

Put the old image tag back in .env and recreate the container. If it cannot read data changed by the new release, restore the backup created before update:

docker compose up -d
./restore.sh ./backups/node-red-PRE-UPDATE.tar.gz

Complete removal

docker compose down stops the service but preserves flows. To remove all application data after verifying an off-server backup:

docker compose down
docker volume rm node-red-data
rm -rf ~/services/node-red

Sources: official Docker guide, securing the editor, and projects and flow files.

Report a recipe problem

Tell us how it went on your server

Opens a prefilled GitHub issue. A GitHub account is required; submitting the issue makes it public.

Troubleshooting

The container exits or stays unhealthy

Check the settings and the required environment variables:

docker compose config
docker compose ps --all
docker compose logs --tail=200 node-red

NODE_RED_ADMIN_PASSWORD_HASH must be a bcrypt hash, not a plain password. Regenerate it with node-red admin hash-pw; then recreate the container.

The editor returns 401 or login fails

Confirm the configured user and hash are present, then force a recreate:

grep '^NODE_RED_ADMIN_USERNAME=' .env
grep '^NODE_RED_ADMIN_PASSWORD_HASH=' .env
docker compose up -d --force-recreate

Do not remove adminAuth from config/settings.js to regain access on a public server. Generate a new password hash instead. Changing the credential secret is unrelated to editor login and makes saved credentials unreadable.

Port 1880 is already in use

Change NODE_RED_PORT in .env, recreate the service, and update the reverse proxy upstream. Keep the localhost bind:

docker compose up -d
docker compose port node-red 1880

A flow does not deploy or a node is missing

Open the sidebar debug panel and inspect the runtime logs:

docker compose logs --tail=200 node-red

Install only reviewed nodes through the palette manager, then export the flow before changing it. A community node is executable code inside the container; removing it can leave dependent flows invalid.

Credentials cannot decrypt after restore

The restored flows_cred.json requires the exact NODE_RED_CREDENTIAL_SECRET that encrypted it. Put the saved secret back in .env, recreate the container, and retry. If the old secret is unavailable, delete the broken credentials only after exporting non-secret flows and enter credentials again; no recovery bypass exists.