- 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
- 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
# DNS Setup
When running FlowFuse on Docker or Kubernetes you will need to be able to setup an entry in a DNS server.
This is because FlowFuse uses hostname based routing to know which Node-RED instance you want to access.
By default the instance name is used in combination with a supplied domain. In this document we will use example.com
as the domain. (It doesn't need to be a "whole" domain, it could also be a sub domain of one you already own. e.g. ff.example.com
).
If you are running Docker/Kubernetes on the same machine as the DNS server and Web Browser do not use 127.0.0.1
as the IP address to point the wild card domain at. This is because the host names will be looked up by the Web Browser, the Forge Application, and the Node-RED instances. The last 2 are running in containers and 127.0.0.1
will resolve to the container, not the entry point.
# Production
For a production deployment you will need to have access to modify DNS, if you are not sure how to set up DNS records talk to whoever manages your DNS.
As mentioned earlier you will need them to create a wildcard DNS entry that points to either the Docker host machine or the Kubernetes Nodes which are running the Ingress Controller.
This can be either:
- a
A
(andAAAA
for IPv6) record pointing to an IP address e.g.*.example.com 8600 A 192.0.2.1
- a
CNAME
record pointing to the hostname of the entry point e.g.*.ff.example.com 8600 CNAME forge.example.com
# AWS ALB Ingress
When using AWS ALB (Application Load Balancer) as an Ingress Controller for FlowFuse deployed into an EKS cluster then you would create a wildcard CNAME entry pointing to the hostname of the ALB
# Digital Ocean
You should create an A record pointing to the public IP address of the Load Balancer created when you install the Nginx Ingress Helm Chart.
# Local Testing and Development
For development and testing we probably only need to set up DNS entries for the developers local machine. The easiest way to do this is to use an application called dnsmasq.
Dnsmasq is a tool that can be used as a DNS caching proxy (and a DHCP server, but we don't need that). We can set it up to point to an upstream DNS server to resolve all normal addresses, but we can also give it a list of hostname/IP address pairs to use locally.
# DNSMasq
Setting up dnsmasq is not too complex, what is harder is setting it up in a way that works well with the network configuration on a laptop that might move between different networks and expects to get its default DNS configuration automatically assigned by DHCP.
The following headings cover how to do this on a number of different operating systems
# Ubuntu
For Docker on Linux you can use 172.17.0.1
as the address for the domain which is the IP address assigned to the docker0
interface.
sudo apt-get install dnsmasq
sudo echo "bind-interfaces" >> /etc/dnsmasq.conf
sudo echo "no-resolv" >> /etc/dnsmasq.conf
sudo echo "conf-dir=/etc/dnsmasq.d" >> /etc/dnsmasq.conf
sudo echo "address=/example.com/172.17.0.1" > /etc/dnsmasq.d/02-flowforge.conf
sudo service dnsmasq restart
sudo echo "DNS=127.0.0.1" >> /etc/systemd/resolved.conf
sudo echo "DOMAINS=~example.com" >> /etc/systemd/resolved.conf
sudo service systemd-resolved restart
# Fedora
For Docker on Linux you can use 172.17.0.1
as the address for the domain which is the IP address assigned to the docker0
interface.
sudo dnf install dnsmasq
sudo echo "bind-interfaces" >> /etc/dnsmasq.conf
sudo echo "no-resolv" >> /etc/dnsmasq.conf
sudo echo "conf-dir=/etc/dnsmasq.d" >> /etc/dnsmasq.conf
sudo echo "address=/example.com/172.17.0.1" > /etc/dnsmasq.d/02-flowforge.conf
sudo systemctl enable dnsmasq.service
sudo service dnsmasq restart
sudo echo "DNS=127.0.0.1" >> /etc/systemd/resolved.conf
sudo echo "DOMAINS=~example.com" >> /etc/systemd/resolved.conf
sudo service systemd-resolved restart
# Windows
Unfortunately dnsmasq will not run on Windows and I have not found something similar yet.
# MacOS
On MacOS you can alias a private IP address to the loop back interface e.g. 10.128.0.1
with
sudo ifconfig lo0 alias 10.128.0.1
You will need install dnsmasq using homebrew
brew install dnsmasq
It appears that the install location differs based on the Apple Hardware. For Intel hardware Macs it's in /usr/local
and for M1 hardware it's /opt/homebrew
. Please check where it installed things when the previous command has completed.
Then edit a configuration file
M1 mac
echo "conf-dir=/opt/homebrew/etc/dnsmasq.d" >> /opt/homebrew/etc/dnsmasq.conf
echo "address=/example.com/10.128.0.1" > /opt/homebrew/etc/dnsmasq.d/ff.conf
Intel mac
echo "conf-dir=/usr/local/etc/dnsmasq.d" >> /usr/local/etc/dnsmasq.conf
echo "address=/example.com/10.128.0.1" > /usr/local/etc/dnsmasq.d/ff.conf
Set dnsmasq to run as a service
sudo brew services start dnsmasq
sudo dscacheutil -flushcache
Tell MacOS to use dnsmasq for our test domain
sudo mkdir -p /etc/resolver
sudo tee /etc/resolver/example.com > /dev/null <<EOF
nameserver 127.0.0.1
domain example.com
search_order 1
EOF
And finally kick the MacOS resolver so it sees the updates
sudo killall -HUP mDNSResponder
# Pi Hole
Pi Hole is a package that bundles dnsmasq as an image to run on a Raspberry Pi (or in Docker container e.g. on your NAS). Its main use is to block advertisements embedded in web pages. But since in its normal configuration it is already handling all the local DNS traffic, making us work with FlowFuse is possible and means you do not need to change any settings on your development/test machine.
Create the following file in /etc/dnsmasq.d
called 02-flowforge.conf
address=/example.com/192.168.0.22
Where 192.168.0.22 is the ipv4 address of the Docker host machine or a Kubernetes node. And example.com
is the domain to use.
After making the change you will probably need to restart things with:
sudo pihole restartdns
If running Pi Hole in Docker then you will need to create the file on the host and mount it to the /etc/dnsmasq.d/02-flowforge.conf
location.
# No Local DNS server
If you really can't run dnsmasq then there is a possible alternative.
A really useful service called sslip.io allows you to test FlowFuse even when you cannot use dnsmasq. You can read more about sslip.io on their web site.
You will need to set the domain
entry in the flowforge.yml
configuration file to the following pattern 172.17.0.1.sslip.io
. Don't forget to replace the IP address with the correct one for your configuration.
This will work because the sslip.io
domain is set up to always return the IP address embedded in the hostname queried.