From b98530513bd9112071ecb2c94695a2561f97b619 Mon Sep 17 00:00:00 2001 From: sumitshinde-84 Date: Thu, 2 Jul 2026 17:00:57 +0530 Subject: [PATCH 1/2] Device agent 4 related documentation update --- .../install/device-agent-installer.md | 4 +-- docs/device-agent/install/docker.md | 25 ++++++++++++++++++- docs/device-agent/install/kubernetes.md | 4 +++ docs/device-agent/install/manual.md | 4 +-- docs/device-agent/install/overview.md | 2 +- docs/device-agent/running.md | 15 ++++++++--- docs/user/http-access-tokens.md | 4 +++ 7 files changed, 49 insertions(+), 9 deletions(-) diff --git a/docs/device-agent/install/device-agent-installer.md b/docs/device-agent/install/device-agent-installer.md index fc264025b5..5ca28e8d01 100644 --- a/docs/device-agent/install/device-agent-installer.md +++ b/docs/device-agent/install/device-agent-installer.md @@ -125,10 +125,10 @@ flowfuse-device-agent-installer.exe --port 1882 To update bundled Node.js runtime, specify the `--update-nodejs` flag with the desired version: ```bash -./flowfuse-device-agent-installer --update-nodejs --nodejs-version 20.19.1 +./flowfuse-device-agent-installer --update-nodejs --nodejs-version 22.11.0 ``` -Specifying `--update-nodejs` without a version will pick the default version defined in the installer. +Specifying `--update-nodejs` without a version will pick the default version defined in the installer. From the Device Agent v4 release, the installer defaults to Node.js 22. ### Device Agent To update the Device Agent package, use the `--update-agent` flag, optionally specifying the version: diff --git a/docs/device-agent/install/docker.md b/docs/device-agent/install/docker.md index 1402e02cd7..d5fd936ccb 100644 --- a/docs/device-agent/install/docker.md +++ b/docs/device-agent/install/docker.md @@ -57,12 +57,35 @@ services: - TZ=UTC ``` +## Running as a non-root user + +From Device Agent v4, the container no longer runs as `root`. It runs as the unprivileged `flowfuse` user (UID `2000` / GID `2000`), following least-privilege security practices. + +This affects bind-mounted files and directories: the mounted path must be readable (and, where the agent needs to write — for example when using a Provisioning Token or a module cache — writable) by UID/GID `2000`. + +Before upgrading an existing container to v4, update the ownership of any mounted directory so the `flowfuse` user can access it: + +```bash +sudo chown -R 2000:2000 /path/to/config/dir +``` + +Alternatively, run the container as a user of your choosing with the `--user` flag: + +```bash +docker run \ + --user 1000:1000 \ + --mount type=bind,src=/path/to/device.yml,target=/opt/flowfuse-device/device.yml \ + -p 1880:1880 \ + flowfuse/device-agent:latest +``` + ## Verify Once running and assigned, access the Node-RED editor at `http://:1880`. ## Notes -- Device Agent 3.x requires Node.js 18 in the base image; the `latest` tag uses Node.js 18. +- Device Agent 4.x defaults to Node.js 22; the `latest` tag now uses Node.js 22. Node.js 20 reached end-of-life in April 2026. +- Device Agent 3.x uses Node.js 18 in the base image. To stay on a specific line, use a fixed tag (for example `3.x` or `2.8.0`) instead of `latest`. - For 2.x, use a fixed tag like `2.8.0` instead of `latest`. - Ensure outbound TCP 443 to `app.flowfuse.com` and `mqtt.flowfuse.cloud` and access to `https://registry.npmjs.com` unless using a module cache. See [Running with no access to npmjs.org](../running.md#running-with-no-access-to-npmjs.org). diff --git a/docs/device-agent/install/kubernetes.md b/docs/device-agent/install/kubernetes.md index 84ccf051c6..0d0646b60b 100644 --- a/docs/device-agent/install/kubernetes.md +++ b/docs/device-agent/install/kubernetes.md @@ -31,6 +31,8 @@ Any deployment on Kubernetes is going to be specific to the environment and requ Choose the approach that matches how you manage device lifecycle and credentials. +> **Non-root container (Device Agent v4+):** From Device Agent v4 the container runs as the unprivileged `flowfuse` user (UID `2000` / GID `2000`) instead of `root`. Any volume the agent must write to — such as the PersistentVolume used for Automatic Provisioning — must be writable by GID `2000`. The examples below set `securityContext.fsGroup: 2000` on the pod so mounted volumes are group-owned by, and writable to, the `flowfuse` user. A read-only Secret mount (as used in Fixed Configuration) is world-readable and needs no change. + ## Fixed Configuration If you have an existing `device.yml` file containing a set of Device Agent credentials. @@ -128,6 +130,8 @@ spec: labels: app: device-one spec: + securityContext: + fsGroup: 2000 # allows the non-root flowfuse user (UID/GID 2000) to write to the PVC initContainers: # on first run copies the device.yml from Secret to PVC volume - name: config-copy image: busybox:latest diff --git a/docs/device-agent/install/manual.md b/docs/device-agent/install/manual.md index 4d3faec2da..d82f2fef9f 100644 --- a/docs/device-agent/install/manual.md +++ b/docs/device-agent/install/manual.md @@ -16,7 +16,7 @@ Use this method if you want direct control over the Node.js runtime and filesyst ## Prerequisites -- Node.js 18 or later installed +- Node.js 18 or later installed (Node.js 22 recommended; supported versions are 18, 20, 22, and 24). Node.js 20 reached end-of-life in April 2026. - Linux, macOS, or Windows - Outbound network access to FlowFuse platform and the NPM registry @@ -125,6 +125,6 @@ sudo npm install -g @flowfuse/device-agent@latest npm install -g @flowfuse/device-agent@latest ``` -If you must stay on 2.x, use `@2.x`. Device Agent 3.x requires Node.js 18+. +If you must stay on 2.x, use `@2.x`. Device Agent 3.x requires Node.js 18+. Device Agent 4.x defaults to Node.js 22 and supports Node.js 18, 20, 22, and 24. [^1]: Run `powershell -Command "Start-Process 'cmd' -Verb RunAs"` to launch an elevated command prompt (e.g. as an admin user) diff --git a/docs/device-agent/install/overview.md b/docs/device-agent/install/overview.md index 677cd967e4..a439e27eb0 100644 --- a/docs/device-agent/install/overview.md +++ b/docs/device-agent/install/overview.md @@ -28,7 +28,7 @@ meta: ## Prerequisites -- Node.js 18 or later (for Manual install and for running locally) +- Node.js 18 or later (for Manual install and for running locally). Supported versions are 18, 20, 22, and 24. Device Agent v4 (and its installer and official Docker image) defaults to Node.js 22 — this is the recommended runtime. Note that Node.js 20 reached end-of-life in April 2026. - Supported OS: Linux, macOS, Windows, or Docker container - Networking: allow outbound access on 443 to: - app.flowfuse.com diff --git a/docs/device-agent/running.md b/docs/device-agent/running.md index 1bc9dca2bb..a7bf04d447 100644 --- a/docs/device-agent/running.md +++ b/docs/device-agent/running.md @@ -71,9 +71,10 @@ Setup command Global Options - -h, --help print out helpful usage information - --version print out version information - -v, --verbose turn on debugging output + -h, --help print out helpful usage information + --version print out version information + -v, --verbose turn on debugging output + -j, --json-logging output logs in JSON format ``` ### Command Line Examples @@ -90,6 +91,14 @@ _Start the agent with a different working directory and the Web UI enabled_ flowfuse-device-agent -d /path/to/working/directory -w --ui-user admin --ui-pass password --ui-port 8081 ``` +## Structured JSON logging + +By default the Device Agent prints plain-text logs, which can be hard to parse with log aggregation tools such as Grafana Loki or AWS CloudWatch. From Device Agent v4, you can output machine-readable, structured logs in JSON format using the `-j`/`--json-logging` flag: + +```bash +flowfuse-device-agent --json-logging +``` + ## Configuring Node.js Options Node.js command-line arguments can be passed to the Node-RED process started by the Device Agent. This is useful for memory-intensive workflows or certificate management. diff --git a/docs/user/http-access-tokens.md b/docs/user/http-access-tokens.md index f00d0c4d88..a7b470e7b3 100644 --- a/docs/user/http-access-tokens.md +++ b/docs/user/http-access-tokens.md @@ -40,3 +40,7 @@ To access it from another Node-RED instance, you can use the `HTTP Request` node option, selecting 'bearer authentication' and providing the token: ![](./images/bearer-token-nr-request.png) + +### Remote Instances + +HTTP Access Tokens can also be used to secure HTTP endpoints served by Node-RED flows running on Remote Instances (devices). This requires [Device Agent v4](../device-agent/introduction.md) or later. On self-hosted FlowFuse, it also requires FlowFuse v2.32 or later; it is already available on FlowFuse Cloud. From a2011c9195bc85b2a37c7cc8c65f506715ab90d7 Mon Sep 17 00:00:00 2001 From: sumitshinde-84 Date: Thu, 2 Jul 2026 17:24:06 +0530 Subject: [PATCH 2/2] Device agent 4 related documentation update --- docs/device-agent/install/device-agent-installer.md | 2 +- docs/device-agent/install/docker.md | 4 ++-- docs/device-agent/install/kubernetes.md | 4 ---- docs/device-agent/running.md | 6 +++--- docs/user/http-access-tokens.md | 2 +- 5 files changed, 7 insertions(+), 11 deletions(-) diff --git a/docs/device-agent/install/device-agent-installer.md b/docs/device-agent/install/device-agent-installer.md index 5ca28e8d01..ad2f5d7b86 100644 --- a/docs/device-agent/install/device-agent-installer.md +++ b/docs/device-agent/install/device-agent-installer.md @@ -125,7 +125,7 @@ flowfuse-device-agent-installer.exe --port 1882 To update bundled Node.js runtime, specify the `--update-nodejs` flag with the desired version: ```bash -./flowfuse-device-agent-installer --update-nodejs --nodejs-version 22.11.0 +./flowfuse-device-agent-installer --update-nodejs --nodejs-version 20.19.1 ``` Specifying `--update-nodejs` without a version will pick the default version defined in the installer. From the Device Agent v4 release, the installer defaults to Node.js 22. diff --git a/docs/device-agent/install/docker.md b/docs/device-agent/install/docker.md index d5fd936ccb..c96a89c9cd 100644 --- a/docs/device-agent/install/docker.md +++ b/docs/device-agent/install/docker.md @@ -61,7 +61,7 @@ services: From Device Agent v4, the container no longer runs as `root`. It runs as the unprivileged `flowfuse` user (UID `2000` / GID `2000`), following least-privilege security practices. -This affects bind-mounted files and directories: the mounted path must be readable (and, where the agent needs to write — for example when using a Provisioning Token or a module cache — writable) by UID/GID `2000`. +This affects bind-mounted directories: the directory the agent uses for its state must be writable by UID/GID `2000`, otherwise the agent will fail to start with a permissions error. Before upgrading an existing container to v4, update the ownership of any mounted directory so the `flowfuse` user can access it: @@ -86,6 +86,6 @@ Once running and assigned, access the Node-RED editor at `http://:188 ## Notes - Device Agent 4.x defaults to Node.js 22; the `latest` tag now uses Node.js 22. Node.js 20 reached end-of-life in April 2026. -- Device Agent 3.x uses Node.js 18 in the base image. To stay on a specific line, use a fixed tag (for example `3.x` or `2.8.0`) instead of `latest`. +- Device Agent 3.x uses Node.js 18 in the base image. To stay on a specific line, use a fixed tag instead of `latest`. - For 2.x, use a fixed tag like `2.8.0` instead of `latest`. - Ensure outbound TCP 443 to `app.flowfuse.com` and `mqtt.flowfuse.cloud` and access to `https://registry.npmjs.com` unless using a module cache. See [Running with no access to npmjs.org](../running.md#running-with-no-access-to-npmjs.org). diff --git a/docs/device-agent/install/kubernetes.md b/docs/device-agent/install/kubernetes.md index 0d0646b60b..84ccf051c6 100644 --- a/docs/device-agent/install/kubernetes.md +++ b/docs/device-agent/install/kubernetes.md @@ -31,8 +31,6 @@ Any deployment on Kubernetes is going to be specific to the environment and requ Choose the approach that matches how you manage device lifecycle and credentials. -> **Non-root container (Device Agent v4+):** From Device Agent v4 the container runs as the unprivileged `flowfuse` user (UID `2000` / GID `2000`) instead of `root`. Any volume the agent must write to — such as the PersistentVolume used for Automatic Provisioning — must be writable by GID `2000`. The examples below set `securityContext.fsGroup: 2000` on the pod so mounted volumes are group-owned by, and writable to, the `flowfuse` user. A read-only Secret mount (as used in Fixed Configuration) is world-readable and needs no change. - ## Fixed Configuration If you have an existing `device.yml` file containing a set of Device Agent credentials. @@ -130,8 +128,6 @@ spec: labels: app: device-one spec: - securityContext: - fsGroup: 2000 # allows the non-root flowfuse user (UID/GID 2000) to write to the PVC initContainers: # on first run copies the device.yml from Secret to PVC volume - name: config-copy image: busybox:latest diff --git a/docs/device-agent/running.md b/docs/device-agent/running.md index a7bf04d447..668f160205 100644 --- a/docs/device-agent/running.md +++ b/docs/device-agent/running.md @@ -74,7 +74,7 @@ Global Options -h, --help print out helpful usage information --version print out version information -v, --verbose turn on debugging output - -j, --json-logging output logs in JSON format + --log-format json output logs in JSON format ``` ### Command Line Examples @@ -93,10 +93,10 @@ flowfuse-device-agent -d /path/to/working/directory -w --ui-user admin --ui-pass ## Structured JSON logging -By default the Device Agent prints plain-text logs, which can be hard to parse with log aggregation tools such as Grafana Loki or AWS CloudWatch. From Device Agent v4, you can output machine-readable, structured logs in JSON format using the `-j`/`--json-logging` flag: +By default the Device Agent prints plain-text logs, which can be hard to parse with log aggregation tools. From Device Agent v4, you can output machine-readable, structured logs in JSON format using the `--log-format json` flag: ```bash -flowfuse-device-agent --json-logging +flowfuse-device-agent --log-format json ``` ## Configuring Node.js Options diff --git a/docs/user/http-access-tokens.md b/docs/user/http-access-tokens.md index a7b470e7b3..a6d66465f0 100644 --- a/docs/user/http-access-tokens.md +++ b/docs/user/http-access-tokens.md @@ -43,4 +43,4 @@ option, selecting 'bearer authentication' and providing the token: ### Remote Instances -HTTP Access Tokens can also be used to secure HTTP endpoints served by Node-RED flows running on Remote Instances (devices). This requires [Device Agent v4](../device-agent/introduction.md) or later. On self-hosted FlowFuse, it also requires FlowFuse v2.32 or later; it is already available on FlowFuse Cloud. +HTTP Access Tokens can also be used to secure HTTP endpoints served by Node-RED flows running on Remote Instances (devices). This requires [Device Agent v4](../device-agent/introduction.md) or later. On self-hosted FlowFuse, it also requires FlowFuse v2.32 or later.