node-red-development

A simple and embedded NodeRED setup for easy Node development

Table of contents

• Table of contents
• Release Notes
  • v0.1.1
  • v0.1.0
• Prerequisites
• Installation
• Configuration
  • VSCode
  • Linters
  • Logger
  • Files
    • package.json
    • settings.js
    • server.js
• Enabling HTTPS
• Enabling User authentication
• Securing http-in endpoints
• Allow access from other networks than localhost
• Installing NodeRED nodes
• NPM Scripts
• Security
• TL;DR
• To do

Release Notes

v0.1.1

• Added VSCode task to enable Prettier for node_modules that are symlinked (yarn link). This task can optionally be run as a preLaunchTask for debugging.
• Added .prettierignore file with basic configuration.
• Added description about how to add a git submodule in the Installing NodeRED nodes section.
• Added local_modules to .gitignore file.
• Added a TL;DR section with a guick install guide of sorts.

v0.1.0

• Initial release

Prerequisites

This project uses yarn for package management. Alternatively you can use npm buy yarn is preferred.

To install yarn:

$ npm install yarn --global

Installation

# Clone this repository into the project folder
$ git clone https://github.com/QNimbus/node-red-development.git
# Install the package dependencies
$ yarn install
# To start the NodeRED server
$ yarn start

Configuration

The most relevant configuration settings can be setup within the config section of package.json. If not set, the default values are used or may be overridden by environment variables. The node-red specific settings are contained in settings.js.

This template project is pre-configured with the following default configuration:

• The default protocol is HTTP
• The default port is 1880
• The default User folder is ./.nodered
• The default Flows file is ./flows.json
• The default static web folder is ./public
• The default URI is /
• The default admin URI is /admin
• Logging is set to verbose with logging level info

The default configuration should work on all platforms including Windows.

VSCode

This project already contains some basic boilerplate settings for use with VSCode. It contains a .vscode/launch.json file and a .vscode/settings.json file. The launch.json file contains a configuration that allows debugging in VSCode using the F5 key. This will start the NodeRED server with debugging options, attaches the debugger and allows for restarting the debugger when Nodemon restarts when it detects source code changes.

Linters

This project contains a basic configuration for ESLint and JSHint to enforce some coding and style guidelines. If you use VSCode along with the ESLint and JSHint extensions you can enforce these during development of your own Node project. Optionally you can also use Prettier which can automatically perform some basic formatting when you edit and save your files. VSCode also has a Prettier extension.

Logger

You can enable the custom loggers in the settings.js file under key logging.

See: Custom logging module

Files

package.json

These are the default settings in package.json. For additional information

 "config" : {
    // The TCP port used by NodeRED (for the editor interface as well as HTTP endpoints)
    "httpPort": "1880",
    // The address on which the NodeJS Express server should listen on (e.g. localhost, 0.0.0.0, 192.168.1.2, et cetera)
    "listeningAddress": "localhost",
    // To use HTTPS set 'useHTTPS' to 'true' and provide server certficates in the project root
    // The server certificate files (server.crt and server.key) can be generated by running:
    // $ yarn create-self-signed -- <common-name>
    "useHTTPS": "false",
    // Some NodeRED settings:
    "nrTitle": "NodeRED Development",
    "nrCredentialSecret": "secret",
    "nrUserFolder": "./.nodered",
    "nrFlowFile": "./.flows.json",
  },

The settings in package.json can be overridden on commandline, e.g.

$ npm run start-debug --node-red-development:httpPort=1234 --node-red-development:useHTTPS=false

settings.js

The NodeRED specific configuration is all in settings.js.

server.js

Make changes to server.js if you need to add/change the ExpressJS server such as adding security using Passport.

Enabling HTTPS

Enabling https is easy following these steps:

1. Change configuration in package.json in the config section and set a useHTTPS to true.
2. run yarn create-self-signed -- <common-name> which will create new self signed certificates.
3. Start the server by yarn start or yarn start-debug

Note: You can provide own signed certificates by the files server.key and server.crt. To create your own certificate and private key you can use OpenSSL:

$ openssl req -newkey rsa:2048 -nodes -keyout server.key -x509 -days 365 -out server.crt

Enabling User authentication

By default everyone has full access to the NodeRED editor. You can limit access by enabling user authentication to the admin interface at adminAuth in settings.js. You can generate passwords with yarn create-auth-password -- <your password>. For further information see http://nodered.org/docs/security.html#generating-the-password-hash

Note: Do not forget to restrict the default permissions in the adminAuth section of settings.js!

Securing http-in endpoints

A great tutorial how to enable JSONWebTokens (JWT) can be found here: Authenticating Node-RED with JSONWebToken.

Allow access from other networks than localhost

Change the listeningAddress in the config section of package.json from localhost to 0.0.0.0 to listening on all network interfaces of your host. Alternatively you can also start the NodeRED server with an additional command line option to override the listeningAddress:

$ npm run start-debug --node-red-development:httpPort=1234 --node-red-development:listeningAddress=0.0.0.0

Installing NodeRED nodes

NodeRED nodes are installed as npm modules. With this project template you have two options when installing new nodes:

1. Project Level

   Make sure you are in the main project folder and install using yarn as usual. This will save the module as a project dependency in the package.json file (or use npm --save-optional). For example:

   $ yarn add node-red-contrib-bigtimer --optional

2. User Level

   Change into your user folder (default location is /.nodered) before using yarn. You might need to run yarn init -y the first time if the package.json file does not exist in that folder.

   $ cd ./nodered
   $ yarn init -y
   $ yarn add node-red-contrib-bigtimer --optional

3. Developing node-red nodes

   If you use the setup to isolate the development of a node-red node you should use yarn link in your repository folder. Then run yarn link <repository-name> in the node-red-development folder to link and install your custom node. Use yarn start-debug to start the node-red instance with debugging features. See npm scripts for more information.

   Note: You can add a Node as a git submodule in a local folder (e.g. local_modules/) and yarn link from there. This way you have all the benefits of the projects linters as well as debugging your Node under development. Do not forget to run yarn install in your cloned submodule to download all it's dependencies. To clone a repository as a submodule:

   $ git submodule add -b master git@github.com:QNimbus/node-red-contrib-openhab-v2.git local_modules/node-red-contrib-openhab-v2

NPM Scripts

Execute "node server.js"

$ yarn start

Start node with active debugging features and NODE_ENV set to development which will not minify RED.

$ yarn start-debug

Generates the hash for the provided password which you can use in settings.js.

$ yarn create-auth-password -- <your password>

Generate self-signed certificate and a private key for when running the server in HTTPS mode. You will need to provide the Common Name (domain name) *

$ yarn create-self-signed -- <common-name>

* WARNING: The server.key and server.crt will be overwritten if they already exist._

Security

Because this template has NodeRED embedded into a standard ExpressJS web server you should apply security using ExpressJS features rather than NodeRED. This gives you far more control overall - however if you need to provide read-only access to the NodeRED admin UI you will also need to configure NodeRED security in the settings.js file (nrSettings.adminAuth). See Securing Node-RED.

TL;DR

Follow these steps to install a working development environment in VSCode for a specific NodeRED Node:

NodeJS

• Install NodeJS for your platform
• Install yarn globally (npm install yarn --global)

VSCode

• Install VSCode extension Prettier
• Install VSCode extension ESLint
• Install VSCode extension JSHint

Repository: QNimbus/node-red-development

• Clone repository into suitable location
  ./> $ git clone https://github.com/QNimbus/node-red-development.git

• Optional: Start a new development branch
  ./> $ git checkout -b dev

• Install dependencies
  ./> $ yarn install

• Clone Node repository as submodule, for example
  ./> $ git submodule add -b master git@github.com:QNimbus/node-red-contrib-openhab-v2.git local_modules/node-red-contrib-openhab-v2

• Install submodule dependencies
  ./local_modules/node-red-contrib-openhab-v2/> $ yarn install

• Link submodule into node-red-development
./local_modules/node-red-contrib-openhab-v2/> $ yarn link
./> $ yarn link node-red-contrib-openhab-v2

• Start VSCode and hit F5 to start debugging!
  Open a browser and go to the NodeRED Admin interface (http://localhost:1880/admin)

To do

• Add middleware to secure http-in endpoints (e.g. nrSettings.httpNodeMiddleware)
• Add more logging options
• Add optional code to include extended security using Passport