Node-RED

Build automation flows connecting devices, APIs and online services.

Choose your deployment and the way you want to use Selfhost. The instructions below follow that choice.

Deployment Use Selfhost with

Set up Node-RED

Create portable native configuration files with managed settings.

Choose Administrator login, or run selfhost app init node-red --method configured.
Sign in as admin using ADMIN_PASSWORD in the private project environment.

Customize deployment inputs (1)

Local HTTP port port: portDefault: 1880

Save this as inputs.json and adjust the values before initialization.

{
  "port": 1880
}

selfhost app --directory ./node-red init node-red --method configured --inputs inputs.json

Initialization writes portable files and does not start the app. Review compose.yaml, the private .env and any files in files/, then start it:

selfhost app --directory ./node-red start

No Selfhost dashboard or background service is needed. You can also start these files directly:

cd node-red
docker compose -f compose.yaml up -d

Start the stack and sign in as admin using ADMIN_PASSWORD in the private project .env.
Keep CREDENTIAL_SECRET stable and back it up with /data; it protects flow credentials.
Editor authentication does not protect HTTP In flow endpoints under /api. Add authentication to those flows or their proxy.
settings.js is ordinary portable JavaScript executed only by Node-RED inside its container.

Connect an existing installation

Use Existing apps → Link an app in the dashboard, or the CLI’s existing-app commands. Choose Node-RED, its URL and, optionally, its exact Docker container on a connected server.

Save existing.json with your app URL. Add server_id and container for container inspection and actions.

{
  "profile": "node-red",
  "name": "Node-RED",
  "url": "https://app.example.com"
}

selfhost existing link --file existing.json
selfhost existing list
selfhost existing inspect EXISTING_ID

Linking enables the existing-app profile’s supported inspection and actions. It does not import Compose or attach the new-deployment settings and onboarding profiles described below.

Existing app commands, permissions and unlinking

Actions for a linked container

Check settings syntax

Check JavaScript syntax in settings.js. This does not validate credentials or flows.

selfhost existing action EXISTING_ID check-settings

Before configuring integrations

Portable files/settings.js configures editor authentication, persistent context and a stable flow encryption key.
Change supported native fields and recreate the container when ready.
HTTP In flow endpoints have their own authentication requirements.
Keep CREDENTIAL_SECRET with your backup; changing it can make existing flow credentials unreadable.
The basic image or a custom settings.js does not consume the generated SELFHOST_ settings automatically.

Node-RED integrations

Compose service: node-red. These operations use the profile saved when this deployment is created.

The SELFHOST_ settings require the Administrator login deployment method and its mounted settings.js. Custom or existing settings.js must explicitly read these variables.

Native settings

Changes use the app’s Compose environment. Unrelated settings are preserved.

Supported fields (5)

Administrator username administrator: Used by the Administrator login deployment method. string
HTTP flow URL prefix http-root: Used by the configured settings.js. HTTP In endpoints need their own authentication. string
Disable editor UI disable-editor: Keeps the authenticated Admin API available. stringChoices: true, false
Log level log-level: stringChoices: fatal, error, warn, info, debug, trace
Enable projects projects: stringChoices: true, false

Save a JSON map of the field IDs you want to change as changes.json. Replace FIELD_ID with an ID from the supported fields above, and use its declared value type. Review the plan and replace REVIEWED_REVISION with the revision it returns.

{
  "FIELD_ID": "YOUR_VALUE"
}

selfhost app --directory ./node-red config node-red
selfhost app --directory ./node-red plan node-red changes.json
selfhost app --directory ./node-red apply node-red changes.json --revision REVIEWED_REVISION

Saved changes need service recreation to become active. Existing interpolated environment values stay under your control in .env or Compose.

App actions

Check settings syntax · schedulable

Check JavaScript syntax in settings.js. This does not validate credentials or flows.

selfhost app --directory ./node-red action node-red check-settings

A workspace can schedule this workflow while Selfhost runs. A standalone user can invoke it through an external scheduler. Scheduling guide.

App configuration reference

Versions and updates

This deployment uses the following images. Existing projects retain their saved recipe and images. A new catalogue version does not silently update them.

node-red: nodered/node-red:5.0.7

Review compatibility and back up app data before an update. Choose an image version and review the change.

Keep control of your setup

Selfhost remains optional. Your app runs using ordinary Compose files, its own settings and persistent data. Keep the Compose project name and volumes to preserve storage. Configuration exports and setting backups do not include application data.

Standalone CLI guide · Backups and removal · Node-RED documentation