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.location, which must already be a location of that GVC. A location that is not on your GVC starts nothing.What Gets Created
env.get() and ${VAR} in node properties cannot read them.
Prerequisites
Create the admin login secret
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.admin.secretName to this name.Create the credential key secret
credentialSecret.secretName to this name.Create the HTTP endpoint login secret (recommended)
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.httpNodeAuth.secretName to this name.Create a secret for flow variables (optional)
env.get(). Only the keys you list in envSecret.keys are exposed.envSecret.secretName to this name and envSecret.keys to the keys to expose.Installation
The required values are the two secret names and the location of your GVC that Node-RED runs in:UI
CLI
Terraform
Pulumi
Configuration
Location and Image
Runtime
contextStorage: memory, flow and global context is lost on every restart.
Snapshots
Logins
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
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
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
publicAccess.enabled: false, the public endpoint refuses requests; reach the editor with cpln port-forward (see Connecting).
Connecting
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
Withbackup.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.
Recovering from a Crashing Flow
SetsafeMode: 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
The workload never becomes ready and logs are empty
The workload never becomes ready and logs are empty
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.Log line cpln-node-red: FATAL ... at least 12 characters
Log line cpln-node-red: FATAL ... at least 12 characters
Nothing runs and get-deployments says maxScale is set to 0
Nothing runs and get-deployments says maxScale is set to 0
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.Every flow stops after a deploy and the log says Failed to load external modules
Every flow stops after a deploy and the log says Failed to load external modules
palette.allowInstall is false. Remove the module from the node, or set palette.allowInstall: true.The login still works with the old password after editing the secret
The login still works with the old password after editing the secret
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.secretNamefor 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.