> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node-RED

> Node-RED low-code flow editor and runtime on one stateful replica with a persistent snapshotted volume, admin login from a secret, optional login on HTTP endpoints and the Dashboard, and pinned extra nodes. Deploys into an existing GVC; two secrets must exist first.

## 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.

> [!NOTE]
>
> 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

| Resource | Name | Purpose | Optional |
| - | - | - | - |
| Workload | `RELEASE_NAME-node-red` | Node-RED (stateful, 1 replica) on HTTP `1880`: editor, admin API, HTTP In endpoints and Dashboard | — |
| Volume set | `RELEASE_NAME-node-red-data` | Data volume mounted at `/data`: flows, encrypted credentials, installed nodes, file-backed context and projects, with scheduled snapshots | — |
| Identity | `RELEASE_NAME-node-red-identity` | Workload identity used to read your secrets | — |
| Policy | `RELEASE_NAME-node-red-policy` | Grants the identity `reveal` on exactly the secrets Node-RED reads | — |

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.

```bash theme={null}
cpln secret create-dictionary --name ADMIN_SECRET_NAME \
  --entry username=admin \
  --entry password="$(openssl rand -hex 16)"
```

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.

```bash theme={null}
printf '%s' "$(openssl rand -hex 32)" | cpln secret create-opaque --name CREDENTIAL_SECRET_NAME --encoding plain -f -
```

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.

```bash theme={null}
cpln secret create-dictionary --name HTTP_AUTH_SECRET_NAME \
  --entry username=api \
  --entry password="$(openssl rand -hex 16)"
```

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.

```bash theme={null}
cpln secret create-dictionary --name ENV_SECRET_NAME \
  --entry API_TOKEN=YOUR_TOKEN
```

Set `envSecret.secretName` to this name and `envSecret.keys` to the keys to expose.

> [!WARNING]
>
> 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:

```bash theme={null}
cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/node-red \
  --version 1.0.0 --gvc GVC_NAME \
  --set location=LOCATION_NAME \
  --set admin.secretName=ADMIN_SECRET_NAME \
  --set credentialSecret.secretName=CREDENTIAL_SECRET_NAME
```

To install, follow the instructions for your preferred method:

> [card] [UI](https://docs.controlplane.com/template-catalog/install-manage/ui.md)
>
> Browse, install, and manage templates visually

> [card] [CLI](https://docs.controlplane.com/template-catalog/install-manage/cli.md)
>
> Manage templates from your terminal

> [card] [Terraform](https://docs.controlplane.com/template-catalog/install-manage/terraform.md)
>
> Declare templates in your Terraform configurations

> [card] [Pulumi](https://docs.controlplane.com/template-catalog/install-manage/pulumi.md)
>
> Declare templates in your Pulumi programs

## Configuration

### Location and Image

```yaml theme={null}
# The ONE location of your GVC that Node-RED runs in; it must already be a GVC location.
location: aws-us-east-1
image: nodered/node-red:5.0.9
resources:
  minCpu: 250m          # keep maxCpu <= 4x minCpu (stateful workload)
  maxCpu: 1000m
  minMemory: 256Mi
  maxMemory: 1Gi
timezone: UTC           # IANA timezone for inject/cron schedules (TZ)
```

### Runtime

```yaml theme={null}
contextStorage: localfilesystem  # localfilesystem (context survives restarts) | memory (upstream default)
safeMode: false         # true = start the editor without running any flow (recover from a crashing flow)
volumeset:
  capacity: 10          # GiB (minimum 10): flows, credentials, installed nodes, context, projects
```

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

### Snapshots

```yaml theme={null}
backup:
  enabled: true         # scheduled snapshots of /data (no bucket needed)
  schedule: "0 3 * * *" # cron, UTC; at most hourly (a single fixed minute)
  retention: 7d         # how long each snapshot is kept, the final one taken at uninstall included
```

### Logins

```yaml theme={null}
admin:
  secretName: my-node-red-admin
credentialSecret:
  secretName: my-node-red-credential-secret
httpNodeAuth:
  secretName: ""        # e.g. my-node-red-http-auth: a `dictionary` with `username` and `password`; "" = endpoints open
```

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](#changing-the-admin-password)).

### Palette

```yaml theme={null}
palette:
  allowInstall: true    # false = the palette manager and function nodes cannot install modules
  packages: []          # pinned name@version installed at boot, e.g. ["@flowfuse/node-red-dashboard@1.36.1"]
```

`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

```yaml theme={null}
projects:
  enabled: false        # git-backed projects in the editor (each project has its own credential key)
```

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

```yaml theme={null}
extraEnv: []            # plain values, e.g. [{name: MQTT_HOST, value: broker.example.com}]
envSecret:
  secretName: ""        # e.g. my-node-red-env: a `dictionary`; each key listed below becomes an env var
  keys: []              # e.g. [API_TOKEN, MQTT_PASSWORD]
```

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

```yaml theme={null}
publicAccess:
  enabled: true         # editor, HTTP In endpoints and Dashboard on the public *.cpln.app URL; the editor always requires a login
internalAccess:
  type: same-gvc        # none | same-gvc | same-org | workload-list
  workloads: []         # used only with workload-list
  # workloads:
  #   - //gvc/GVC_NAME/workload/WORKLOAD_NAME
```

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

## Connecting

| What | Address | Credentials |
| - | - | - |
| Editor (public) | `status.canonicalEndpoint` of `cpln workload get RELEASE_NAME-node-red --gvc GVC_NAME -o yaml` | the admin login |
| Editor (private) | `cpln port-forward RELEASE_NAME-node-red 1880:1880 --gvc GVC_NAME`, then `http://localhost:1880` | the admin login |
| HTTP In endpoints | `https://ENDPOINT/PATH`, or `http://RELEASE_NAME-node-red.GVC_NAME.cpln.local:1880/PATH` inside the GVC | the HTTP endpoint login, when set |
| Admin API | the same address as the editor; a token from `POST /auth/token` | the admin login |

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:

```bash theme={null}
curl -s -X POST https://ENDPOINT/auth/token -H 'Content-Type: application/json' \
  -d '{"client_id":"node-red-admin","grant_type":"password","scope":"*","username":"admin","password":"YOUR_ADMIN_PASSWORD"}'
curl -s https://ENDPOINT/flows -H 'Authorization: Bearer ACCESS_TOKEN'
```

## Operations

### Changing the Admin Password

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

```bash theme={null}
cpln secret edit ADMIN_SECRET_NAME
cpln workload force-redeployment RELEASE_NAME-node-red --gvc GVC_NAME
```

### 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:

```bash theme={null}
cpln volumeset snapshot create RELEASE_NAME-node-red-data --gvc GVC_NAME --snapshot-name SNAPSHOT_NAME --location LOCATION_NAME --volume-index 0
cpln volumeset snapshot get RELEASE_NAME-node-red-data --gvc GVC_NAME
```

### 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.

```bash theme={null}
cpln volumeset snapshot restore RELEASE_NAME-node-red-data --gvc GVC_NAME --snapshot-name SNAPSHOT_NAME --location LOCATION_NAME --volume-index 0
```

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

> [accordion] The workload never becomes ready and logs are empty
>
> 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`.

> [accordion] Log line cpln-node-red: FATAL ... at least 12 characters
>
> The admin password is shorter than 12 characters (the credential key needs 16). Update the secret and force a redeployment.

> [accordion] 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.

> [accordion] Every flow stops after a deploy and the log says Failed to load external modules
>
> 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`.

> [accordion] The login still works with the old password after editing the secret
>
> 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

> [card] [Node-RED Documentation](https://nodered.org/docs/)
>
> Official user guide and cookbook

> [card] [Securing Node-RED](https://nodered.org/docs/user-guide/runtime/securing-node-red)
>
> Editor and HTTP endpoint authentication

> [card] [Admin HTTP API](https://nodered.org/docs/api/admin/)
>
> Tokens, flows and nodes over HTTP

> [card] [Node-RED Dashboard 2.0](https://dashboard.flowfuse.com/)
>
> Dashboard nodes served at /dashboard
