# Docker Install

This guide walks you through detailed set up of FlowFuse Platform on a Docker container environment using Docker Compose. Typically suited for small/medium on premise deployments.
By the end, you will have a fully functioning FlowFuse instance running in a Docker container.

The following guide walks through a full production-ready deployment. If you want to install FlowFuse for evaluation purposes, please refer to the [Quick Start Guide](/docs/quick-start).

## Checklist

<div className="grid,grid-cols-2,gap-8">
<div className="checklist">
<label>

Prerequisites

</label>


    <div>
<checklist-item task="Domain Name">



</checklist-item>


      <checklist-item task="Docker Engine & Docker Compose">



</checklist-item>


      <checklist-item type="recommended" task="Setup Dedicated Database">



</checklist-item>


      <checklist-item type="recommended" task="Prepare TLS Certificates">



</checklist-item>
</div>
</div>


  <div className="checklist">
<label>

Installation

</label>


    <div>
<checklist-item task="Download FlowFuse">



</checklist-item>


      <checklist-item task="Configure FlowFuse">



</checklist-item>


      <checklist-item type="recommended" task="Enable HTTPS">



</checklist-item>
</div>
</div>
</div>

## Prerequisites

Before you begin, ensure you have the following:

1. **Domain Name & DNS:** A domain name that you own and can configure DNS settings for (explained in [DNS](#dns))
2. **Install Docker:** [Docker Engine](https://docs.docker.com/engine/) and [Docker Compose](https://docs.docker.com/compose/install/) (in `2.23.1` version or higher) must be installed on your system (either as a standalone binary or as docker plugin).

For a production-ready environment, we also recommend:

- **Database:** Prepare dedicated database on a external database server (see [FAQ](#how-to-use-external-database-server) for more details)
- **TLS Certification:** Prepare TLS certificate for your domain and configure FlowFuse platform to use it (see [Enable HTTPS](#enable-https-optional))

### Requirements

To run the FlowFuse platform smoothly, we recommend the following minimum hardware specs:

- CPU: 2 cores
- Memory: 4 GB RAM
- Storage: 20 GB disk space
Each Node-RED instance you host will uses 0.1 CPU cores and 256 MB of memory by default. This parameters can be adjusted in admin area of FlowFuse platform. Keep this in mind when sizing your hardware, especially if plan to create multiple hosted instances.

When deploying the FlowFuse platform behind a firewall or proxy, ensure that the following ports are open and forwards a traffic to the server where FlowFuse is installed:

- Port `80` (HTTP)
- Port `443` (HTTPS)

#### AWS Elastic Container Service

At this time we do not support deploying FlowFuse to AWS's Elastic Container Service.

### DNS

The orchestration uses an instance of Nginx to route requests to each Node-RED instance. To do this it needs each instance to have a unique hostname, to generate this the instance name is prepended to a supplied domain.

To make this work you will need to configure a DNS server to map a [wildcard domain entry](https://en.wikipedia.org/wiki/Wildcard_DNS_record) to the IP address of the host running Docker. e.g `*.example.com`.

The FlowFuse Application will be hosted on `http://forge.example.com`

**Note** At this moment FlowFuse platform is not capable to run on localhost. You must point your domain to the external IP address of the host machine, not the loopback address (`127.0.0.1`).

Notes on how to setup DNS can be found [here](/docs/install/dns-setup).

## Installing FlowFuse

### Download installation files

Download the latest version of the FlowFuse Docker Compose file and example `.env` file used for installation configuration:

```bash
curl -L -o docker-compose.yml https://github.com/FlowFuse/docker-compose/releases/latest/download/docker-compose.yml
curl -L -o .env https://raw.githubusercontent.com/FlowFuse/docker-compose/refs/heads/main/.env.example
```

### Configure

Installation configuration is done via the `.env` file.
The minimal configuration required is the domain name you will be using for the platform.

Edit downloaded `.env` file with the editor of your choice and update the `DOMAIN` variable with the domain you will be using for the platform.

Alternatevily, use `sed` to update the `DOMAIN` variable in the `.env` file:

```bash
sed -i 's/^DOMAIN=.*/DOMAIN=example.com/' .env
```

Please note that once set, the `DOMAIN` value should not be changed as it is used as part of the configuration stored in the database of each Node-RED instance. The ability to migrate to different domain is on the feature backlog.

### Enable HTTPS (optional)

If you want to serve the FlowFuse platform and Node-RED instances over TLS you will need to obtain a wildcard TLS certificate for the domain you are using eg `*.example.com`. If you are running on an Internet facing machine you can use our configuration files to generate it atomatically.

Otherwise you will need to contact a SSL Certificate vendor and configure Nginx manually.

#### Automatic TLS Certificate

**Note: Automatic TLS generation is possible only for the publicly available servers**

In the `.env` file, set the `TLS_ENABLED` variable to `true`:

```bash
TLS_ENABLED=true
```

Proceed to the [next paragraph](#start-flowfuse-platform) to start the platform with automatically generated TLS certificate.

> When using automatic TLS certificate generation, the platform will take a few minutes to generate them on the first platform startup.
> For a short period of time browsers may report untrusted certificate warning. This is expected behavior and should resolve itself once the certificate is generated.

#### Custom TLS Certificate

If you have own TLS certificate, you can use it in FlowFuse platform installation as well. As mentioned before, the certificate must be a wildcard one for the domain you are using.

<div className="ff-callout,ff-callout--note">

Note

<div className="ff-callout__content">

If your TLS certificate is issued by a private Certificate Authority, additional configuration is required so that Hosted Instances trust the CA. See [What additional configuration is required when the TLS certificate is issued by a private Certificate Authority?](#what-additional-configuration-is-required-when-the-tls-certificate-is-issued-by-a-private-certificate-authority) for the step-by-step instructions.

</div>
</div>

To configure FlowFuse platform with your certificate, you need to have:

- certificate key file
- certificate's full chain (server certificate and intermediate certificates bundled into single file)

To add your certificate to the platform, edit the `.env` file downloaded earlier and set values for `TLS_ENABLED`, `TLS_CERTIFICATE` and `TLS_KEY` variables. `TLS_ENABLED` variable should be set to `true`.
`TLS_CERTIFICATE` should contain the full chain of the certificate while `TLS_KEY` should contain the key file.
Example of `.env` file with the custom TLS certificate configuration:

```bash
TLS_ENABLED=true
TLS_CERTIFICATE="
-----BEGIN CERTIFICATE-----
MIIFfzCCBKegAwIBAgISA0
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIFfzCCBKegAwIBAgISA0
...
-----END CERTIFICATE-----
"
TLS_KEY="
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQD
...
-----END PRIVATE KEY-----
"
```

## Start FlowFuse platform

**Note: Make sure all configuration are done above before proceeding.**

**Note: Commands must be executed within the same directory where the Docker Compose and .env files are located.**

#### With automatic TLS certificate generation

```bash
docker compose --profile autotls -p flowfuse up -d
```

#### In all other scenarios, including custom TLS certificate

```bash
docker compose -p flowfuse up -d
```

The platform will take a few minutes to start up. You can check the status of the containers by running:

```bash
docker compose -p flowfuse ps
```

Visit `forge.example.com` (replace `example.com` with the domain configured in the `.env` file) in your browser to access the FlowFuse platform.

## First Run Setup

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

For more information, follow [this guide](/docs/install/first-run).

Once you have finished setting up the admin user there are some Docker specific items to consider.

## Upgrade

**Note: If you are upgrading from version 2.10.0 or lower, please follow this guide**

1. Find the Docker Compose project name:
```bash
docker compose ls
```


The output will show the project name, as well as the location of Docker Compose file used for creating the project.
2. Stop the existing project (replace `$projectName` with your project name):
```bash
docker compose -p $projectName down --rmi all
```
3. Download the latest Docker Compose files:
```bash
curl -L -o docker-compose.yml https://github.com/FlowFuse/docker-compose/releases/latest/download/docker-compose.yml
```
4. Make sure the `.env` file is present and contains your installation-specific configuration. Download an example `.env` file if needed:
```bash
curl -o .env.example https://raw.githubusercontent.com/FlowFuse/docker-compose/refs/heads/main/.env.example
```
5. Pull the latest version of the default stack container (and any other stacks you have configured)
```bash
docker pull flowfuse/node-red:latest
```
6. Start the project depending on the TLS configuration (replace `$projectName` with your project name):

- automatic TLS:
```bash
docker compose --profile autossl -p $projectName up -d
```
- any other scenario:
```bash
docker compose -p $projectName up -d
```

## Common Questions

### How to use external database server?

FlowFuse platform uses PostgreSQL database to store its data. By default, the database is created and managed by the Docker Compose.
If you want to use an external database server, you need to:

- on your database server, create `flowforge` and `ff-context` databases as well as a user with access to both of them (see `configs.postgres_db_setup` and `configs.postgres_context_setup` in the `docker-compose.yml` file for the reference)
- configure the connection to the database in the `.env` file. Set the `DB_HOST`, `DB_USER`, `DB_PASSWORD` variables to the connection details of the external database server

Once ready, [start the application](#start-flowfuse-platform) .

### How can I provide my own TLS certificate?

If you have your own TLS certificate, you can use it in FlowFuse platform installation as well. See [Enable HTTPS](#enable-https-optional) section for more details.

Additionally, if your TLS certificate is issued by a private Certificate Authority, you will need to perform some additional configuration to make hosted Node-RED instances trust the CA. See [What additional configuration is required when the TLS certificate is issued by a private Certificate Authority](#what-additional-configuration-is-required-when-the-tls-certificate-is-issued-by-a-private-certificate-authority) for the step-by-step instructions.

### What additional configuration is required when the TLS certificate is issued by a private Certificate Authority?

When the FlowFuse platform is configured with a TLS certificate issued by a private Certificate Authority (CA), hosted Node-RED instances will not trust the CA by default. As a result, opening the editor for a hosted instance will fail with a certificate trust error.

To make hosted Node-RED instances trust the private CA, follow the steps below:

1. **Update the environment file.** In the `.env` file created during the installation process, set `DOCKER_DRIVER_PRIVATE_CA_PATH` to the path of your Certificate Authority certificate file. This must be the path to the file stored on the Docker host server. For example, if the `ca.pem` file is located at `/usr/local/ssl/ca.pem`:```bash
DOCKER_DRIVER_PRIVATE_CA_PATH="/usr/local/ssl/ca.pem"
```
2. **Modify the Compose file.** In the `docker-compose.yml` file used to create the FlowFuse Docker stack, uncomment the `NODE_EXTRA_CA_CERTS` environment variable and the corresponding volume mount on the `forge` service so the certificate is passed correctly to the platform. You can apply both changes with a single `sed` command:```bash
sed -i.bak -E -e 's/^#([[:space:]]*- "NODE_EXTRA_CA_CERTS=)/\1/' -e 's/^#([[:space:]]*- \$\{DOCKER_DRIVER_PRIVATE_CA_PATH\})/\1/' docker-compose.yml && rm docker-compose.yml.bak
```
3. **Restart the Forge service** to apply the changes:```bash
docker compose restart forge
```
4. **Apply changes to running instances.** Once the platform is online, manually suspend and start all running hosted instances so they pick up the new TLS settings.

### I would like to invite my team members to the platform with e-mail, how can I do that?

In order to configure FlowFuse platform with external e-mail server, you need to adjust `EMAIL_*` variables in the `.env` file.
Find the `.env` file end edit `Email configuration` section with following details:

- `EMAIL_ENABLED` - set to `true` to enable e-mail functionality
- `EMAIL_HOST` - provide SMTP server host
- `EMAIL_PORT` - provide SMTP server port (default is `587`)
- `EMAIL_SECURE` - set to `true` if the connection should be secured
- `EMAIL_USER` - provide SMTP server username
- `EMAIL_PASSWORD` - provide SMTP for the user defined in `EMAIL_USER`

Restart the core application to apply the changes:

```bash
docker compose restart forge
```

### Connection Refused error

After starting the platform, I can't access it in the browser - I see "Connection Refused error"

If you are using the Digital Ocean Docker Droplet to host FlowFuse you will need to ensure that port 80 & 443 are opened in the UFW firewall before starting.

FlowFuse platform is running on ports 80 and 443, so you need to open these ports in the firewall. Below are examples of commands to open these ports:

Ubuntu:

```bash
sudo ufw apply http
sudo ufw apply https
```

CentOS:

```bash
sudo firewall-cmd --zone=public --add-service=http --permanent
sudo firewall-cmd --zone=public --add-service=https --permanent
sudo firewall-cmd --reload
```

Windows (command prompt):

```bash
netsh advfirewall firewall add rule name="Open Port 80" dir=in action=allow protocol=TCP localport=80
netsh advfirewall firewall add rule name="Open Port 443" dir=in action=allow protocol=TCP localport=443
```

Windows (PowerShell):

```powershell
New-NetFireWallRule -DisplayName 'WSL 8080TCP' -Direction Inbound -LocalPort 8080 -Action Allow -Protocol TCP
New-NetFireWallRule -DisplayName 'WSL 8080TCP' -Direction Outbound -LocalPort 8080 -Action Allow -Protocol TCP
```

### I installed FlowFuse on Windows with WSL2, application is running but I can't access it in the browser

Next to [opening the ports in the firewall](#connection-refused-error),
you need to configure port forwarding from Windows host to WSL2 server.

To forward traffic from an external IP to your container, run the following PowerShell command (administrator privileges required):

```powershell
netsh interface portproxy add v4tov4 listenport=80 listenaddress=0.0.0.0 connectport=80 connectaddress=127.0.0.1
```

This command forwards traffic from port 80 on your external IP address to port 80 on your localhost, where the Nginx Proxy container is listening for connections.

### How can I enable persistent storage for Node-RED instances?

Node-RED instances running in Docker do not have direct access to a persistent file system to store files or use for storing context data.

FlowFuse includes a File Storage service that can be enabled to provide persistent storage.

To disable the default File nodes, edit the Template and add `10-file.js,23-watch.js` to the "Exclude nodes by filename" section

![undefined](/docs/install/images/file-node-template.png)FlowFuse Docker Compose files includes FlowFuse File Storage component by default and starts it along with the platform.

Full details on configuring the File Storage service are available [here](/docs/install/file-storage).

## Uninstall

- Bring the services down with `docker compose -p flowfuse down -v` (note the extra `-v` to delete all the volumes, only include this if you do not want to reuse this install)
- Use `docker images` to list container images
- Use `docker rmi [imagename]:[tag]` to remove all images that start with `flowfuse/`