Add design note for standalone Node-RED

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
 

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.
+
+<img src='installer.png' width='400'>
+
+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.
+
+<img src='trayicon.png'> <img src='trayicon2.png'>
+
+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

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.
+
+<img src='installer.png' width='400'>
+
+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.
+
+<img src='ide.png' width='600'>
+
+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.
+
+<img src='logging.png' width='300'>
+
+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