# Upgrading FlowFuse

If you are upgrading an existing FlowFuse installation, this page will list any
particular requirements needed to upgrade to a given level.

If you are upgrading across multiple versions, make sure you check the requirements
for each version you are upgrading across.

Note that we do not support downgrading FlowFuse to previous levels once an upgrade
has been performed.

## General guideline

Details of how to upgrade can be found for each deployment model:

- [LocalFS](/docs/contribute/local#upgrade)
- [Docker](/docs/install/docker#upgrade)
- [Kubernetes](/docs/install/kubernetes#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](/docs/upgrade/nodered-version).

### Upgrading to 2.31.2

#### Kubernetes: MQTT broker is now EMQX

From Helm chart v2.78.0 (FlowFuse 2.31.2), the chart deploys [EMQX](https://www.emqx.io/)
as the platform MQTT broker, replacing Mosquitto. The migration happens automatically as
part of upgrading the chart; it is not possible to stay on Mosquitto when using the Helm
chart. If the broker is enabled, the
[EMQX Operator](https://docs.emqx.com/en/emqx-operator/latest/getting-started/getting-started.html)
must be installed on the cluster before upgrading, otherwise the upgrade will fail.

See [MQTT Broker configuration](/docs/install/configuration#mqtt-broker-configuration)
for which platform features depend on the broker.

### Upgrading to 2.6.0

#### Required AWS EKS configuration change

This release introduces the new Embedded Editor which integrates the Node-RED editor with the FlowFuse dashboard when using Node-RED 4.0. This has required some changes to be made on how certain HTTP headers are passed between the NGINX Ingress controller and AWS NLB.

The following configuration change must be applied otherwise users will not be able to login to Node-RED 4.0 instances.

The following configuration needs to be added in the values passed to the ingress-nginx helm chart. See [full configuration](https://flowfuse.com/docs/install/kubernetes/aws/#nginx-ingress) for the reference.

```text
controller:
   config:
      use-proxy-protocol: true
   service:
      annotations:
         service.beta.kubernetes.io/aws-load-balancer-target-group-attributes: proxy_protocol_v2.enabled=true
   externalTrafficPolicy: Cluster
```

The Proxy Protocol feature will be enabled only on newly created Target Groups.
To enable the Proxy Protocol on an existing Target Group, manual intervention is required. For detailed instructions, please refer to the [official AWS documentation](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html#enable-proxy-protocol).

#### Persistent Storage

As part of this release there is a new option for Persistent File Storage for Kubernetes based deployments.
This change removes the need to use the customised File Nodes and the FlowFuse File Server by mounting a
Persistent Volume into the Pods running the instances.

To enable this feature the following needs to be created

- A Kubernetes StorageClass that points to storage provider that can
dynamically provision new Persistent Volumes. e.g. the [AWS EFS CSI driver](https://github.com/kubernetes-sigs/aws-efs-csi-driver)
- Pass the following values to the FlowFuse Helm Chart
```text
forge:
  persistentStorage:
    enabled: true
    storageClass: '<name of StorageClass>'
    size: '5Gi'
```


Where size is the default size for the volume.

Details for how to setup a AWS EFS backed StorageClass can be found on the aws-efs-csi-driver [site](https://github.com/kubernetes-sigs/aws-efs-csi-driver/blob/master/docs/efs-create-filesystem.md).

### Upgrading to 2.0.0

> **⚠️**  Breaking changes introduced!

Together with new application features, this **release 2.0.0 introduces breaking changes** in Flowfuse Helm chart.
If you are managing your local Flowfuse instance using our [Helm Chart](https://github.com/FlowFuse/helm/tree/main/helm/flowfuse), please refer to the [upgrade](/docs/install/kubernetes#upgrade) section of the Kubernetes installation guide or the Helm Chart [README.md](https://github.com/FlowFuse/helm/blob/main/helm/flowfuse/README.md#upgrading-chart) for more details.

### Upgrading to 1.10

Endpoint Rate Limiting is now available to FlowFuse. This is disabled by default, but can be enabled by setting the `rate_limits.enabled` config setting to `true`.
The documentation for this is available [here](/docs/install/configuration#rate-limiting-configuration).

The [TeamType concept](/docs/user/concepts#team-type) was expanded in this release.
It is used to control what Instance Types are available for different teams, as
well as any additional limits that should be applied. When creating new Instance
Types, they must now be [manually enabled](/docs/admin/introduction#managing-instance-types)
for the Team Types on the platform.

### Upgrading to 1.5

The main change in this release was a change in our terminology around the individual
Node-RED instances. We have introduced the [Application concept](/docs/user/concepts#application)
as a way to group individual [Node-RED instances](/docs/user/concepts#instance) (what we previously called Projects).

The term 'Project' is being phased out. You may still see it crop up, such as
in some of the external APIs, but we're working our way through removing it.

### Upgrading to 1.3

To enable the Team Library and FlowFuse-based Authentication of HTTP routes each
Node-RED instance will need to be updated to the [latest Stack](/docs/user/changestack).

#### Persistent Context added

The new Persistent Context feature is available to projects when running with a
[premium license](/docs/upgrade/open-source-to-premium).

This feature requires additional configuration to be added to the File Server component
that was introduced in FlowFuse 1.1.

Details of how to configure this can be found at the following links:

- [LocalFS](/docs/install/file-storage#localfs)
- [Docker and Kubernetes](/docs/install/file-storage#configuring)

### Upgrading to 1.1

#### File Server added

This release introduces a system for supporting persistent file storage when running on
Docker or Kubernetes (it will also work with LocalFS, but is not required as projects
have access to the hosts filesystem).

Details of how to configure this can be found at the following links:

- [LocalFS](/docs/install/file-storage#localfs)
- [Docker and Kubernetes](/docs/install/file-storage#configuring)

### Upgrading to 0.8

#### MQTT Broker added

This release introduces an MQTT Broker into the FlowFuse platform used to communicate
between devices and the core platform.

For LocalFS users, they will need to manually setup the broker and ensure it is
properly configured. The documentation for this is available [here](/docs/contribute/local#setting-up-mosquitto-optional)

#### LocalFS Users

With the 0.8 release we have updated the version of the SQLite3 module used by the localfs
container driver. We are moving from v5.0.2 to v5.0.8.

There appears to be a clash with the bcrypt module when doing an in place upgrade of the
SQLite3 module that gives an error similar to the following:

```bash
npm ERR! path /opt/share/projects/flowforge/sqlite-test/node_modules/sqlite3
npm ERR! command failed
npm ERR! command sh -c node-pre-gyp install --fallback-to-build
npm ERR! sh: line 1: node-pre-gyp: command not found
```

If you see this then the simplest fix is to remove the `node_modules` directory and reinstall
the modules.

#### Project Nodes

This release adds support for the new Project Link nodes that can be used to send
messages between projects seamlessly.

These nodes require the MQTT Broker to be properly configured.

To deploy flows using these nodes to a Device will require the Device to be running
the latest 0.2.0 release. They will also need to have their credentials regenerated
once the MQTT Broker has been added.

### Upgrading to 0.7

The 0.7 release introduces the [ProjectType concept](/docs/user/concepts#instance-type).

After upgrading to 0.7, an administrator must perform the following tasks before
users will be able to create new projects:

1. Create a Project Type.

  1. On the Administrator Settings -> Project Types page, click 'Create project type'.
  2. Provide a name and description. If you have billing enabled, copy in the default
  Stripe Product/Price IDs from your runtime settings file.
  3. Click 'create'
2. Assign your existing stacks to that type

  1. On the Administrator Settings -> Stacks page, edit each existing stack via
  the drop-down menu in the table.
  2. As a one-time action, set its Project Type to the one just created.
  3. Click 'save'. This will update the stack *and* all existing projects to
  be associated with the new Project Type