From d8f924d88fe9898312f49817c0da6c6e65e9dcb0 Mon Sep 17 00:00:00 2001 From: Rob Marcer <92092324+robmarcer@users.noreply.github.com> Date: Mon, 15 Jun 2026 13:19:55 +0100 Subject: [PATCH 1/4] docs: explain upgrading the Node-RED version via Stacks Major Node-RED upgrades (e.g. Node-RED 5.0) are not delivered through an in-platform update button - they require creating a new Stack pinned to the new container, then moving Instances onto it. Add a generalised guide under docs/upgrade covering this, using the move to 5.0 as the worked example, and link it from the upgrade overview. --- docs/upgrade/README.md | 3 ++ docs/upgrade/nodered-version.md | 79 +++++++++++++++++++++++++++++++++ 2 files changed, 82 insertions(+) create mode 100644 docs/upgrade/nodered-version.md diff --git a/docs/upgrade/README.md b/docs/upgrade/README.md index 3a4862d009..97decaec8e 100644 --- a/docs/upgrade/README.md +++ b/docs/upgrade/README.md @@ -25,6 +25,9 @@ Details of how to upgrade can be found for each deployment model: - [Docker](../install/docker/README.md#upgrade) - [Kubernetes](../install/kubernetes/README.md#upgrade) +To upgrade the version of Node-RED your Instances run (for example, moving to +Node-RED 5.0), see [Upgrading the Node-RED version](./nodered-version.md). + ### Upgrading to 2.6.0 #### Required AWS EKS configuration change diff --git a/docs/upgrade/nodered-version.md b/docs/upgrade/nodered-version.md new file mode 100644 index 0000000000..b52327bd0e --- /dev/null +++ b/docs/upgrade/nodered-version.md @@ -0,0 +1,79 @@ +--- +navTitle: Upgrading the Node-RED version +meta: + description: Upgrade the Node-RED version your self-hosted FlowFuse Instances run by creating a new Stack, using the move to Node-RED 5.0 as a worked example. + tags: + - nodered + - stack + - upgrade + - flowfuse + - self-hosted +--- + +# Upgrading the Node-RED version + +A new major version of Node-RED - such as Node-RED 5.0 - does **not** arrive +through an in-editor or in-platform "update" button. The version of Node-RED an +Instance runs is defined by its [Stack](../user/concepts.md#stack). To move to a +new major version you add it as a new Stack, then point your Instances at it. + +This page uses the move to **Node-RED 5.0** as a worked example, but the same +steps apply to any major Node-RED version upgrade. + +## Why there's no update button + +The notification and one-click upgrade you may have seen applies to new *versions +of an existing Stack* (see [Managing Stacks](../admin/introduction.md#managing-stacks)). +Crossing a major Node-RED version is different: you create a new Stack that pins +the new container, rather than upgrading the existing Stack in place. This keeps +the two versions side by side so you can move Instances over at your own pace. + +## Before you start + +- You will need access to **Admin Settings**. +- Add the new Node-RED version as a **distinct new Stack** rather than editing your + existing Stack. Keeping them separate means your current Instances stay on their + existing version until you choose to move them, and you can switch back from an + Instance's settings if needed. + +## Create the new Stack + +1. Go to **Admin Settings → Stacks**. +2. Click **Create Stack**. +3. Set the **Container Location** to the image for the new Node-RED version. The + exact value depends on your deployment model - see the deployment-specific + guides below. For Node-RED 5.0 on Docker or Kubernetes this is + `flowfuse/node-red:2.31.2-5.0.x`; the full list of pre-built tags is on + [Docker Hub](https://hub.docker.com/r/flowfuse/node-red/tags). +4. Save the Stack. It is now available when you create or migrate Instances. + +For the details of how the Container Location is specified for each deployment +model, see: + +- [Local Stacks](../contribute/local/stacks.md) +- [Docker Stacks](../install/docker/stacks.md) +- [Kubernetes Stacks](../install/kubernetes/stacks.md) + +## Use the new Stack + +### For a new Instance + +Select the new Stack when you create the Instance. It starts on the new Node-RED +version right away. + +### For an existing Instance + +Move the Instance onto the new Stack by following +[Changing the Stack](../user/changestack.md): open the Instance's **Settings** +tab and use **Change Instance Stack** to select the new Stack. The Instance +restarts on the new Stack. + +## Good to know + +- You can switch an Instance back to its previous Stack from the same Settings + page, as long as the old Stack still exists. +- Test the new version on a single Instance before moving production workloads + across. + +Questions? [Reach out to FlowFuse support](https://flowfuse.com/support/) - we're +happy to help. From b8473707a282b09a388c2962e101179f1b235875 Mon Sep 17 00:00:00 2001 From: Rob Marcer <92092324+robmarcer@users.noreply.github.com> Date: Mon, 15 Jun 2026 14:10:03 +0100 Subject: [PATCH 2/4] docs: trim Node-RED version upgrade page to match docs style Drop the 'Good to know' and 'Questions?' footer sections (no other doc uses them) and simplify the intro/meta wording. --- docs/upgrade/nodered-version.md | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/docs/upgrade/nodered-version.md b/docs/upgrade/nodered-version.md index b52327bd0e..dd8ed731c6 100644 --- a/docs/upgrade/nodered-version.md +++ b/docs/upgrade/nodered-version.md @@ -1,7 +1,7 @@ --- navTitle: Upgrading the Node-RED version meta: - description: Upgrade the Node-RED version your self-hosted FlowFuse Instances run by creating a new Stack, using the move to Node-RED 5.0 as a worked example. + description: Upgrade the Node-RED version your self-hosted FlowFuse Instances run by creating a new Stack and moving Instances onto it. tags: - nodered - stack @@ -17,8 +17,8 @@ through an in-editor or in-platform "update" button. The version of Node-RED an Instance runs is defined by its [Stack](../user/concepts.md#stack). To move to a new major version you add it as a new Stack, then point your Instances at it. -This page uses the move to **Node-RED 5.0** as a worked example, but the same -steps apply to any major Node-RED version upgrade. +This page uses the move to **Node-RED 5.0** as an example, but the same steps +apply to any major Node-RED version upgrade. ## Why there's no update button @@ -67,13 +67,3 @@ Move the Instance onto the new Stack by following [Changing the Stack](../user/changestack.md): open the Instance's **Settings** tab and use **Change Instance Stack** to select the new Stack. The Instance restarts on the new Stack. - -## Good to know - -- You can switch an Instance back to its previous Stack from the same Settings - page, as long as the old Stack still exists. -- Test the new version on a single Instance before moving production workloads - across. - -Questions? [Reach out to FlowFuse support](https://flowfuse.com/support/) - we're -happy to help. From 5362d5a70668c24b15c8a1f21417a384406c4c31 Mon Sep 17 00:00:00 2001 From: Rob Marcer <92092324+robmarcer@users.noreply.github.com> Date: Tue, 16 Jun 2026 09:42:44 +0100 Subject: [PATCH 3/4] Update docs/upgrade/nodered-version.md Co-authored-by: Ben Hardill --- docs/upgrade/nodered-version.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/upgrade/nodered-version.md b/docs/upgrade/nodered-version.md index dd8ed731c6..79eab8a6b4 100644 --- a/docs/upgrade/nodered-version.md +++ b/docs/upgrade/nodered-version.md @@ -27,6 +27,8 @@ of an existing Stack* (see [Managing Stacks](../admin/introduction.md#managing-s Crossing a major Node-RED version is different: you create a new Stack that pins the new container, rather than upgrading the existing Stack in place. This keeps the two versions side by side so you can move Instances over at your own pace. +It also ensures major version upgrades are not automatically applied by the +Scheduled Maintenance feature. ## Before you start From 1e728293a7ffd201a3bed463f15e0aad298265d2 Mon Sep 17 00:00:00 2001 From: Rob Marcer <92092324+robmarcer@users.noreply.github.com> Date: Tue, 16 Jun 2026 09:45:25 +0100 Subject: [PATCH 4/4] Update docs/upgrade/nodered-version.md Co-authored-by: Ben Hardill --- docs/upgrade/nodered-version.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/upgrade/nodered-version.md b/docs/upgrade/nodered-version.md index 79eab8a6b4..8d4084433a 100644 --- a/docs/upgrade/nodered-version.md +++ b/docs/upgrade/nodered-version.md @@ -47,6 +47,7 @@ Scheduled Maintenance feature. guides below. For Node-RED 5.0 on Docker or Kubernetes this is `flowfuse/node-red:2.31.2-5.0.x`; the full list of pre-built tags is on [Docker Hub](https://hub.docker.com/r/flowfuse/node-red/tags). + (tags are of the form [FlowFuse Version]-[Node-RED Version]) 4. Save the Stack. It is now available when you create or migrate Instances. For the details of how the Container Location is specified for each deployment