diff --git a/README.md b/README.md index edbbee4..416c533 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,7 @@ with enough detail to review the intent and direction of the feature. - [Node Timeout API](designs/timeout-api.md) - [Overwrite Values in settings.js](designs/overwrite-settings.md) - [Admin API Authentication](designs/admin-api-authentication.md) + - [Node-RED installer](designs/standalone-nodered/README.md) #### In-progress diff --git a/designs/standalone-nodered/README.md b/designs/standalone-nodered/README.md new file mode 100644 index 0000000..d4d393f --- /dev/null +++ b/designs/standalone-nodered/README.md @@ -0,0 +1,122 @@ +--- +state: draft +--- + +# Node-RED installer + +## Summary + +The Node-RED installer is a single installer file to sets up the Node-RED environment. + +## Authors + + - @kazuhitoyokoi + +## Use Cases + + - Easy installation + + With the Node-RED installer UI, it will be easy for users to set up the Node-RED environment. + Especially, the target users are beginners who have no CLI skills to install Node-RED using commands like `npm install`. + + - Offline installation + + It is suitable for offline use cases because it contains Node.js necessary components to execute Node-RED. + If needed, Node-RED nodes can also be included in the installer by custom building. + +## Scope + +### Installer +- Installer sets up Node-RED application to a user environment. +- Easy update using installer including nodes. + + + +Fig.1 Installer + +### Behaviors + +After installing the Node-RED environment, it behaves as a server. +To identify server the process from users, there is a Node-RED icon on the task tray area. + + + +Fig.2 Icon on the task tray + +The Node-RED icon has the menu to handle the Node-RED environment. +As the minimum options, users can select the option to open Node-RED on the default browser or the option to stop the Node-RED server. + +### Prerequisites + The Node-RED installer already has included both Node.js and Node-RED. + Therefore, Node.js is not required when users develop the flow using default Node-RED nodes on the palette. + +- Node.js + + If users want to install additional Node-RED nodes to your Node-RED environment built by the installer, they need the npm command. + [Node.js installer](https://nodejs.org/) which have been provided by the Node.js community sets up both Node.js and npm command but it is useful for installing npm command rather than Node.js in the Node-RED installer case. + The Node.js installer is a simple way to prepare the npm command because the installer UI is easy to operate. + (Node-RED installer can include npm module as dependencies in package.json file but API of the npm module seems not to be public. + To avoid the sudden API change in the future, the npm module is not suitable for the installer.) + +- Git command + + If users would like to use the project feature, they need the git command. + On Windows environment, users install git command by [git installer](https://git-scm.com/). + For macOS users, Xcode is an easy way to install the git command. + The Node-RED environment prepared by the installer will enable the project feature when the git command exists. + +### Logging + For investigating error logs by other users, the standalone Node-RED outputs the logs to files with log rotate style. + +## Details +### Node.js in Node-RED installer + The Node-RED installer includes the latest LTS version of Node.js. + In the Electron project, the higher version of the LTS is used among the two LTS Node.js. + In terms of the Node.js version, there is no relation between Node.js in the installer and Node.js which was installed by the Node.js installer. + (In the node installation process only, later Node.js is used via npm command internally.) + +### Node-RED node installation + The npm command installs Node-RED nodes for Node.js which is installed with the npm command by the Node.js installer. + If there is binary code in the Node-RED node, the rebuilding process is required. + There are the following cases when the process is needed. + + - Rebuilding Node-RED node + + After installing the Node-RED node using the npm command, `electron-rebuild` rebuilds the node to compatible with Node.js in the Electron. + To realize the handling, `postInstall` in RED.hooks API will be used. + + - Rebuilding all Node-RED nodes + + In case of upgrading the Node-RED installer in the future, installed Node-RED nodes should be rebuilt because they will not be compatible with the upgraded Node.js. + This case will occur when the major version of Node.js is changed only. + Therefore, the first version of the Node-RED installer doesn't need to care about the handling. + +### Runtime + The Node-RED runtime will be executed as a single instance. + + Instead of default `~./node-red/` directory, the Node-RED uses `~./node-red-standalone/` directory to avoid changing the default environment under `~/.node-red/` directory. + When there is no `settings.js` file under `~/.node-red-standalone/` directory, the standalone Node-RED saves the default `settings.js` file to load the custom settings in the following table. + + | key | value | + | ---------------------------- | ----- | + | editorTheme.projects.enabled | true | + +### Logging + Users can also see historical log data from log files. + If the `electron-log` module is used to implement logging functionality, the following paths are default file paths to store log data. + + - Windows: C:\Users\\< User name >\AppData\Roaming\node-red\logs\file.log + - macOS: ~/Library/Logs/node-red/file.log + - Linux: /var/log/node-red.log + +### Building binaries + `npm run build` command builds binaries for the following OS environments. + + - Windows (msi) + - macOS (dmg) + + The procedures about how to build other binaries like deb and rpm will be available in the documentation. + +## History + + - 2021-11-30 - Initial proposal diff --git a/designs/standalone-nodered/desktop.md b/designs/standalone-nodered/desktop.md new file mode 100644 index 0000000..4669249 --- /dev/null +++ b/designs/standalone-nodered/desktop.md @@ -0,0 +1,120 @@ +--- +state: draft +--- + +# Standalone Node-RED + +## Summary + +The standalone Node-RED is a desktop version of Node-RED which includes Node-RED, Node.js, nodes, and browser engine using Chromium. + +## Authors + + - @kazuhitoyokoi + +## Use Cases + + - Easy installation + + With the Node-RED installer, it will be easy for users to set up the Node-RED environment. + Especially, the targets are users who have no CLI skills to install Node-RED using commands like `npm install`. + + - Offline installation + + It is suitable for offline use cases because it contains all necessary components to execute Node-RED. + + - Integrated Development Environment (IDE) + + The standalone Node-RED behaves as IDE application like VS Code or Eclipse. + Therefore, users may want to switch multiple projects for various environments on their single computer. + Additionally, they need git functionality as default to proceed with team development or backup their flows. + +## Scope + +### Installer +- Installer setups Node-RED application to a user environment. +- Easy update using installer including nodes. + + + +Fig.1 Installer + +### IDE +- The following behaviors are the same as the normal Node-RED. + - Flow deployment to local runtime + - Flow import and export via clipboard or file upload/download + - Project features +- JSON file association + - The standalone Node-RED opens the flow file using the JSON file association. + - The standalone Node-RED saves the flow to the opened file when deploying it or exiting the application. + + + +Fig.2 The scope of IDE (Red means the standalone specific) + +### Logging +- Flow developers can check the log on the event log window. +- For investigating error log by other users, the standalone Node-RED outputs the logs to files withe log rotate style. + + + +Fig.3 Logging + +## Details + +### Flow editor window + The window is used for the Node-RED flow editor. After executing the standalone Node-RED, the window will be opened automatically. + + - Dialog when closing window + + When closing the window without saving the flow, the window show dialog to select "save & exit" or "cancel". + It is implemented using electron dialog or Node-RED notify UI. + + - Debug window, event log window + + To check the debug tab and event log in another window, users can open these UIs in a single window. + (To realize this functionality, The event log UI in Node-RED core requires ”Open in new window” button which is same as debug tab) + +### Runtime + The Node-RED runtime will be executed when the standard Node-RED starts. + Not to execute the flow until clicking the deploy button (same behavior as run button other IDEs), it runs in the `--safe` mode as default. + In case of executing the flow immediately in the start-up process, `--normal` mode should be set as an option to disable `--safe` mode. + + - Admin API + + The URL to connect between window and runtime uses a random path and fixed port number because the flow editor needs to be prohibited from other users and allow access REST API endpoints using http-in nodes which require the fixed port number. The following URL is an example of the admin API which window accesses. + + http://localhost:1880/< random path > + + - settings.js file + + Instead of default `~./node-red/` directory, the standalone Node-RED uses `~./node-red-standalone/` directory to avoid changing the current environment under `~/.node-red/` directory. + The standalone Node-RED has the default `settings.js` file. When there is no `settings.js` file under `~/.node-red-standalone/` directory, the standalone Node-RED saves the default `settings.js` file to load the custom settings in the following table. + + | key | value | + | ---------------------------- | ----- | + | editorTheme.projects.enabled | true | + + The git command is a prerequisite if users want to use the project feature. + Node-RED automatically detects git command and enables the feature if it is installed. + +### Logging + Users can see log data in real-time on the event log window. On the other hand, users can also see historical log data from log files. + If the `electron-log` module is used to implement logging functionality, the following paths are default file paths to store log data. + + - Windows: C:\Users\\< User name >\AppData\Roaming\node-red\logs\file.log + - macOS: ~/Library/Logs/node-red/file.log + - Linux: /var/log/node-red.log + +### Building binaries + `npm run build` command builds binaries for the following OS environments. + + - Windows (msi) + - macOS (dmg) + - Linux (tar.gz) + + The procedures about how to build other binaries like deb and rpm will be available in the documentation. + +## History + + - 2019-05-19 - Initial proposal diff --git a/designs/standalone-nodered/ide.png b/designs/standalone-nodered/ide.png new file mode 100644 index 0000000..e33b905 Binary files /dev/null and b/designs/standalone-nodered/ide.png differ diff --git a/designs/standalone-nodered/installer.png b/designs/standalone-nodered/installer.png new file mode 100644 index 0000000..700811a Binary files /dev/null and b/designs/standalone-nodered/installer.png differ diff --git a/designs/standalone-nodered/logging.png b/designs/standalone-nodered/logging.png new file mode 100644 index 0000000..82c6fd2 Binary files /dev/null and b/designs/standalone-nodered/logging.png differ diff --git a/designs/standalone-nodered/trayicon.png b/designs/standalone-nodered/trayicon.png new file mode 100644 index 0000000..f02b5f5 Binary files /dev/null and b/designs/standalone-nodered/trayicon.png differ diff --git a/designs/standalone-nodered/trayicon2.png b/designs/standalone-nodered/trayicon2.png new file mode 100644 index 0000000..147d564 Binary files /dev/null and b/designs/standalone-nodered/trayicon2.png differ