# Local Install

This version of the FlowForge platform is intended for running on a single machine for a smaller deployment (e.g. evaluation or home user).

# 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
Windows 10

[^1]: Arm6 devices, such as the original Raspberry Pi Zero and Zero W are not supported.

# Node.js

FlowForge requires Node.js v16.

# 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.

On Windows, the standard Node.js installer will offer to do that for you.

On MacOS, you will need the XCode Command Line Tools to be installed. This can be done by running the following command:

xcode-select --install

# Mosquitto

The platform depends on the Mosquitto MQTT Broker to provide real-time messaging between devices and the platform.

We do not support sharing a broker with other non-FlowForge applications. If you already have mosquitto installed and running, you will need to run a second instance dedicated to FlowForge

This is currently an optional component - the platform will work without the broker, but some features will not be available.

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 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 a configuration file with the following contents:

per_listener_settings false
allow_anonymous false
listener 1883 0.0.0.0
listener 1884 0.0.0.0
protocol websockets
auth_plugin /mosquitto/go-auth.so
auth_opt_backends http
auth_opt_hasher bcrypt
auth_opt_cache true
auth_opt_auth_cache_seconds 30
auth_opt_acl_cache_seconds 90
auth_opt_auth_jitter_second 3
auth_opt_acl_jitter_seconds 5
auth_opt_http_host localhost
auth_opt_http_port 3000
auth_opt_http_getuser_uri /api/comms/auth/client
auth_opt_http_aclcheck_uri /api/comms/auth/acl

You will need to customise the values to match your local configuration:

auth_plugin - set to the path of the go-auth.so file built in the previous step
listener 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.

# 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
```

Create a mosquitto.conf file with the following values:

per_listener_settings false
allow_anonymous false
listener 1883 0.0.0.0
listener 1884 0.0.0.0
protocol websockets
auth_plugin /mosquitto/go-auth.so
auth_opt_backends http
auth_opt_hasher bcrypt
auth_opt_cache true
auth_opt_auth_cache_seconds 30
auth_opt_acl_cache_seconds 90
auth_opt_auth_jitter_second 3
auth_opt_acl_jitter_seconds 5
auth_opt_http_host 172.17.0.1
auth_opt_http_port 3000
auth_opt_http_getuser_uri /api/comms/auth/client
auth_opt_http_aclcheck_uri /api/comms/auth/acl

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 Forge platform
auth_opt_http_port if you have changed the port the Forge platform is running on

Start the container with the following command
```
docker run -d -v /full/path/to/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.

# Installing FlowForge

Create a directory to be the base of your FlowForge install. For example: /opt/flowforge or c:\flowforge

For Linux/MacOS:
```
sudo mkdir /opt/flowforge
sudo chown $USER /opt/flowforge
```
For Windows:
```
mkdir c:\flowforge
```
Download the Installer zip file from https://github.com/flowforge/installer/releases

Unzip the downloaded file into a temporary location and copy its contents to the FlowForge directory

For Linux/MacOS:

cd /tmp/
unzip flowforge-installer-x.y.z.zip
cp -R flowforge-installer-x.y.z/* /opt/flowforge

For Windows:

cd c:\temp
tar -xf flowforge-installer-x.y.z.zip
xcopy /E /I flowforge-installer-x.y.z c:\flowforge

Run the installer and follow the prompts

For Linux/MacOS:
```
cd /opt/flowforge
./install.sh
```
For Windows:
```
cd c:\flowforge
install.bat
```

# Installing as a service

On Linux, the installer will ask if you want to run FlowForge 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 FlowForge directory to that user.

# Configuring FlowForge

The default FlowForge configuration is provided in the file /opt/flowforge/etc/flowforge.yml.

For more details on the options available, see the configuration guide.

# Running FlowForge

If you have installed FlowForge as a service, it can be started by running:

service flowforge start

To run it manually, you can use:

Linux/MacOS:
```
/opt/flowforge/bin/flowforge.sh
```
Windows:

Use the file bin/flowforge.bat in the FlowForge directory

# First Run Setup

Once FlowForge is started, you can access the platform in your browser at http://localhost:3000.

The first time you access it, the platform will take you through creating an administrator for the platform and other configuration options.

For more information, follow this guide.

# Upgrade

To upgrade to v0.3 you can follow these steps.

Stop FlowForge sudo service flowforge stop [^2]
cd /opt/flowforge/app
sudo -u flowforge npm install @flowforge/flowforge@0.3.0 [^3]
Use the editor of your choice to update /opt/flowforge/etc/flowforge.yml to add host: 0.0.0.0 (if you need to access from other than localhost)
Restart FlowForge sudo service flowforge start [^2]

You will then need to create a Project Stack and Project Template before you can create any more projects. See this guide for more information.

If you are running as your normal user you can drop the sudo -u flowforge and just run npm install @flowforge/flowforge@0.2.0

[^2]: Assumes you are running Flowforge as a Linux service. [^3]: Assumes you are running Flowforge as the flowforge user as created by the installer