Skip to main content

Overview

Node-RED is a low-code flow editor and runtime: you wire APIs, MQTT devices, webhooks, schedules and databases together as flows in the browser and deploy them with one click. This template deploys a single Node-RED on a persistent volume with daily snapshots, the editor behind an admin login taken from a secret, an optional login on HTTP endpoints and the Dashboard, and pinned extra nodes installed at start. Node-RED is Apache-2.0 licensed, with no paid tier or feature gate.
This template does not create a GVC. It deploys into an existing GVC that you already have, and Node-RED runs only in the one location named by location, which must already be a location of that GVC. A location that is not on your GVC starts nothing.

What Gets Created

Node-RED has no clustering, so there is no replica setting: a second copy would run every flow, schedule and MQTT subscription twice. The chart creates no secrets. The settings file is generated at every start from your values; the admin and HTTP endpoint passwords are hashed when Node-RED starts, and every credential variable is removed from the process environment before flows run, so env.get() and ${VAR} in node properties cannot read them.

Prerequisites

1

Create the admin login secret

Create a dictionary secret with username and password. The password must be at least 12 characters; Node-RED refuses to start with a shorter one. The secret is read on every start.
Set admin.secretName to this name.
2

Create the credential key secret

Create an opaque secret of at least 16 characters. It encrypts every password and token your flows store. Keep a copy and never change it: credentials saved under another key cannot be decrypted.
Set credentialSecret.secretName to this name.
3

Create the HTTP endpoint login secret (recommended)

Create a dictionary secret with username and password. It puts a login on every HTTP In endpoint and on the Dashboard, including the Dashboard’s live-data socket. Without it they are open to anyone who can reach the endpoint, so set it for anything public.
Set httpNodeAuth.secretName to this name.
4

Create a secret for flow variables (optional)

Create a dictionary secret whose keys become environment variables flows can read with env.get(). Only the keys you list in envSecret.keys are exposed.
Set envSecret.secretName to this name and envSecret.keys to the keys to expose.
The admin login and credential key secrets must exist before you install. If one does not, the deployment waits silently: cpln logs returns nothing, and the only place the missing secret is named is status.versions[].message in cpln workload get-deployments RELEASE_NAME-node-red --gvc GVC_NAME -o yaml. Create the secret, then run cpln workload force-redeployment RELEASE_NAME-node-red --gvc GVC_NAME.

Installation

The required values are the two secret names and the location of your GVC that Node-RED runs in:
To install, follow the instructions for your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Location and Image

Runtime

With contextStorage: memory, flow and global context is lost on every restart.

Snapshots

Logins

The editor always requires the admin login. httpNodeAuth protects HTTP In endpoints and the Dashboard, including its live-data socket (/dashboard/socket.io). With it empty, HTTP In endpoints and the Dashboard are open, and anyone who can reach the Dashboard can read its data and press its buttons. Set it for anything public, or turn publicAccess.enabled off. The admin secret is re-applied on every start: to change the login, edit the secret and force a redeployment (see Changing the Admin Password).

Palette

palette.packages entries must be pinned name@version. They are installed into /data with npm when the list changes; an unchanged list skips npm, so a registry outage does not block a restart. Removing an entry does not uninstall the module. A package that fails to install stops the start with a cpln-node-red: FATAL: log line. Nodes installed from the editor’s palette manager are kept on the volume too. With palette.allowInstall: false, neither the palette manager nor function nodes can install modules. A function node that names a module it cannot install stops every flow from starting, so remove the module from the node (or allow installs) before deploying. Dashboard. Add @flowfuse/node-red-dashboard@1.36.1 to palette.packages (or install it from the palette manager); it serves /dashboard on the same port as the editor. With httpNodeAuth set, the Dashboard pages and its live-data socket both require the HTTP endpoint login.

Projects

With projects.enabled: true the editor offers to create or clone a git project. Each project asks for its own credential key, which the chart does not manage; keep a copy of it. A project commit needs its files staged first, and the git user must be set (the editor asks on first use).

Environment for Flows

Flows read these with env.get('NAME'). Node-RED reads the variables at start, so after changing the secret run cpln workload force-redeployment RELEASE_NAME-node-red --gvc GVC_NAME.

Access

With publicAccess.enabled: false, the public endpoint refuses requests; reach the editor with cpln port-forward (see Connecting).

Connecting

Read the logins back with cpln secret reveal ADMIN_SECRET_NAME -o yaml. To verify the install, get an admin API token, then call the API with it:

Operations

Changing the Admin Password

Edit the secret, then restart Node-RED so it re-reads it:

Backing Up

With backup.enabled: true, /data is snapshotted on backup.schedule and once more when the release is uninstalled; each snapshot is kept for backup.retention. Take one on demand and list them:

Restoring a Backup

Restoring a snapshot replaces /data and restarts Node-RED onto it. Flows, credentials, installed nodes, context and projects all return to the snapshot’s state; anything written since is gone.
The credential key secret must be the one in place when the snapshot was taken.

Recovering from a Crashing Flow

Set safeMode: true and upgrade: the editor starts without running any flow, and your flows stay stored. Fix the flow in the editor, deploy it, then set safeMode: false.

Scaling and Availability

Node-RED runs as a single replica by design. Every upgrade, restart or secret change restarts it, and flows, HTTP endpoints and the Dashboard pause for that time. Inject nodes set to run at start fire again.

Troubleshooting

A prerequisite secret does not exist. Read status.versions[].message with cpln workload get-deployments RELEASE_NAME-node-red --gvc GVC_NAME -o yaml, create the named secret, then run cpln workload force-redeployment RELEASE_NAME-node-red --gvc GVC_NAME.
The admin password is shorter than 12 characters (the credential key needs 16). Update the secret and force a redeployment.
location is not one of your GVC’s locations, so Node-RED is scaled to zero everywhere and the install still reports success. Check the GVC’s locations with cpln gvc get GVC_NAME -o yaml, then upgrade with a location it has.
A function node names a module that cannot be installed while palette.allowInstall is false. Remove the module from the node, or set palette.allowInstall: true.
The admin secret is read at start. Run cpln workload force-redeployment RELEASE_NAME-node-red --gvc GVC_NAME.

Important Notes

  • Editor access is shell access. Function and exec nodes run any code in the container, so treat the admin login like a shell password. Node-RED has no sign-in rate limit; keep the password long.
  • Never change or delete the credential key secret; stored flow credentials become unreadable.
  • Set httpNodeAuth.secretName for any public install; without it HTTP In endpoints and the Dashboard are open.
  • Inbound raw TCP and UDP ports (TCP In nodes, an embedded broker) are not exposed; MQTT nodes work as outbound clients to any broker.
  • Uninstalling deletes the volume set after a final snapshot kept for backup.retention; the secrets you created are not deleted.

External References

Node-RED Documentation

Official user guide and cookbook

Securing Node-RED

Editor and HTTP endpoint authentication

Admin HTTP API

Tokens, flows and nodes over HTTP

Node-RED Dashboard 2.0

Dashboard nodes served at /dashboard