- docs
- FlowFuse User Manuals
- Using FlowFuse
- Getting Started
- Static asset service
- Bill of Materials
- FlowFuse Concepts
- Changing the Stack
- Custom Hostnames
- Device Groups
- DevOps Pipelines
- Environment Variables
- FlowFuse Assistant
- FlowFuse File Nodes
- FlowFuse Persistent Context
- FlowFuse Project Nodes
- High Availability mode
- HTTP Access Tokens
- Instance Settings
- Logging
- Shared Team Library
- Snapshots
- Teams
- User Settings
- FlowFuse API
- Migrating a Node-RED project to FlowFuse
- Device Agent
- Device Agent
- FlowFuse Device Agent Introduction
- Quick Start
- Installation
- Quick Start with Web UI
- Register your Device
- Running the Agent
- Deploying your Flows
- Hardware Guides
- FlowFuse Cloud
- FlowFuse Cloud
- FlowFuse Self-Hosted
- Quick Start
- Installing FlowFuse
- Overview
- Configuring FlowFuse
- DNS Setup
- Docker install
- Docker from AWS Market Place
- Docker on Digital Ocean
- Add Project Stacks on Docker
- Docker Engine on Windows
- Email configuration
- First Run Setup
- FlowFuse File Storage
- Install FlowFuse on Kubernetes
- Upgrading FlowFuse
- Administering FlowFuse
- Administering FlowFuse
- Configuring Single Sign-On (SSO)
- Licensing
- Monitoring
- Telemetry
- User Management
- Support
- Community Support
- Premium Support
- Debugging Node-RED issues
- Contributing
- Contributing to FlowFuse
- Introduction
- Adding Template Settings
- API Design
- Creating debug stack containers
- Database migrations
- FlowFuse Architecture
- Local Install
- State Flows
- Device Editor
- Invite External Users
- User Login Flows
- Reset Password Flow
- Project Creation
- Instance states
- User Sign up Flow
- Team creation Flow
- Working with Feature Flags
# Local Install
This guide is for setting up FlowFuse on a single machine, ideal for smaller deployments, evaluations, or for contributors who want to gain a basic understanding of the FlowFuse platform and its features.
Note: Local installation does not support HTTPS
# Prerequisites
# Operating System
The install script has been tested against the following operating systems:
- Raspbian/Raspberry Pi OS versions Buster/Bullseye [1]
- Debian Buster/Bullseye
- Fedora 35
- Ubuntu 20.04
- CentOS 8/RHEL 8/Amazon Linux 2
- MacOS Big Sur & Monterey on Intel & Apple M processors
- Windows 10 & 11
# Node.js
FlowFuse requires Node.js v18.
# Linux
The install script will check to see if it can find a suitable version of Node.js. If not, it will offer to install it for you.
It will also ensure you have the appropriate build tools installed that are often needed by Node.js modules to build native components.
# Windows/MacOS
If the install script cannot find a suitable version of Node.js, it will exit.
You will need to manually install it before proceeding. Information about how to do this can be found on the Node.js website here: https://nodejs.org/en/download
You will also need to install the appropriate build tools.
- Windows: the standard Node.js installer will offer to do that for you.
- MacOS: you will need the
XCode Command Line Tools
to be installed. This can be done by running the following command:xcode-select --install
# Installing FlowFuse
-
Create a directory to be the base of your FlowFuse install. For example:
/opt/flowforge
orc:\flowforge
For Linux/MacOS:
sudo mkdir /opt/flowforge
sudo chown $USER /opt/flowforgeFor Windows:
mkdir c:\flowforge
-
Download the latest Installer zip file into a temporary location.
-
Unzip the downloaded zip file and copy its contents to the FlowForge directory
# For Linux/MacOS:
Assumes
/tmp/
is the directory where you downloadedflowforge-installer.zip
cd /tmp/
unzip flowforge-installer.zip
cp -R flowforge-installer/* /opt/flowforge# For Windows:
Assumes
c:\temp
is the directory where you downloadedflowforge-installer.zip
cd c:\temp
tar -xf flowforge-installer.zip
xcopy /E /I flowforge-installer c:\flowforge -
Run the installer and follow the prompts
For Linux/MacOS:
cd /opt/flowforge
./install.shFor Windows:
cd c:\flowforge
install.bat
# Installing as a service (optional)
On Linux, the installer will ask if you want to run FlowFuse as a service. This will mean it starts automatically whenever you restart your device.
If you select this option, it will ask if you want to run the service as the current user, or create a new flowforge
user. If you choose to create the user, it will also change the ownership of the FlowFuse directory to that user.
# Configuring FlowFuse
The default FlowFuse configuration is provided in the file flowforge.yml
- Linux/MacOS:
/opt/flowforge/etc/flowforge.yml
- Windows:
c:\flowforge\etc\flowforge.yml
The default configuration file already contains everything you need to get started with FlowFuse.
It will allow you to access FlowFuse and the Node-RED instances you create, from the same server running the platform. If you want to allow access from other devices on the network, you must edit the configuration file and change the host
setting to 0.0.0.0
and change base_url
to contain the IP address of the server.
NOTE: We do not support changing the host
and base_url
values once you have created an instance. For more information on all of the options available, see the configuration guide.
# Running FlowFuse
To run it manually, you can use:
-
Linux/MacOS:
/opt/flowforge/bin/flowforge.sh
-
Windows:
c:\flowforge\bin\flowforge.bat
Or to run as a service:
-
Linux
service flowforge start
# First Run Setup
Once FlowFuse is started, you will be ready to perform the first run setup.
Follow this guide to continue.
# Setting up Mosquitto (optional)
The platform depends on the Mosquitto MQTT Broker to provide real-time messaging between devices and the platform.
This is currently an optional component - the platform will work without the broker, but some features will not be available.
We do not support sharing a broker with other non-FlowFuse applications. If you already have mosquitto installed and running, you will need to run a second instance dedicated to FlowFuse.
You can either follow the manual install steps, which involve building the authentication plugin from scratch, or make use of the Docker install.
# Manual install
Note: if you are running on Windows, you will need to follow the Docker install instructions below due to a limitation of the authentication plugin we use.
Follow the appropriate install instructions for your operating system.
Once installed, you can download pre-built binaries for Linux platforms from here and then jump to step 4 below.
On MacOS you will need to build and install the authentication plugin.
-
Clone the plugin repository
git clone https://github.com/iegomez/mosquitto-go-auth.git
-
Follow the instructions on building the plugin
-
This should result in a file called
go-auth.so
being generated -
Run mosquitto with the configuration file found in the
broker
directoryYou will need to customise the values to match your local configuration:
auth_plugin
- set to the path of thego-auth.so
file built in the previous steplistener 1883/1884
- if you already have mosquitto running locally, you'll need to change these ports to something else.auth_opt_http_host
/auth_opt_http_port
- if you plan to run the platform on a different port, change these settings to match.
mosquitto -c broker/mosquitto.conf
# Docker Install
Instead of installing and building mosquitto and the authentication plugin from source, you can use a pre-built docker image that provides everything needed.
-
First pull the latest version of the pre-built container
docker pull iegomez/mosquitto-go-auth
-
A default mosquitto.conf file can be found in the
broker
directory.You will need to customise the values to match your local configuration:
auth_opt_http_host
value to match the IP address of either the docker0 interface or the external IP address of the machine running the FlowFuse platformauth_opt_http_port
if you have changed the port the FlowFuse platform is running onauth_plugin
should be changed toauth_plugin /mosquitto/go-auth.so
-
Start the container with the following command
docker run -d -v /opt/flowforge/broker/mosquitto.conf:/etc/mosquitto/mosquitto.conf -p 1883:1883 -p 1884:1884 --name flowforge-broker iegomez/mosquitto-go-auth
This will map the
1883
/1884
ports to the host machine so they can be accessed outside of the container. If you already have an MQTT broker running on port 1883, then you'll need to modify the-p
options to use a different set of ports. For example:-p 9883:1883 -p 9884:1884
.
# File Server
By default the FlowFuse File Server component is disabled as it is a licensed feature. If you provide a license you can start the File Server with the following command:
sudo service flowforge-file start
You can then uncomment the following section in the /opt/flowforge/etc/flowforge.yml
file
#################################################
# File Server config #
#################################################
fileStore:
url: http://localhost:3001
# Upgrade
If upgrading from 1.x.y to 2.x.y then you may need to upgrade from NodeJS v16 to NodeJS v18. Please ensure you do this before the following steps.
To upgrade to the latest release you can follow these steps. Replace x.y.z
with the version you are upgrading to.
- Stop FlowFuse
sudo service flowfuse stop
[2] - Change into the
app
directorycd /opt/flowforge/app
(Linux/MacOS)cd c:\flowforge\app
(Windows)
- NPM install the desired version
sudo -u flowforge npm install @flowfuse/flowfuse@x.y.z
(Linux/MacOS) [3]npm install @flowfuse/flowfuse@x.y.z
(Windows)
- Check the release notes for any additional steps needed to upgrade the particular version
- Restart FlowFuse
sudo service flowfuse start
[2:1]
If you are running as your normal user you can drop the sudo -u flowfuse
and just run npm install @flowfuse/flowfuse@x.y.z
# Uninstall
To uninstall, stop all the running processes and then delete the /opt/flowfuse
or c:\flowfuse\
directory.