docs: add networking requirements page for self-hosted installs - #8354
Conversation
There is no outbound egress list for a self-hosted platform in the docs. The only list lives on the Device Agent overview page and covers agent to Cloud traffic, so self-hosters behind a firewall read Cloud-only endpoints as authoritative for their install. Adds docs/install/networking-requirements.md as reference material: one table of always-required destinations, one table of per-feature destinations with the config flag that removes each. Hostnames and defaults taken from the platform source and the Helm chart. Linked from the install overview and from the Docker and Kubernetes prerequisites.
|
This follows a conversation with Nick, and solves a sales need from https://github.com/FlowFuse/accounts/issues/128#issuecomment-5452823013 Up fro changes and considerations as eng sees fit. This is just the initial proposal to kickstart it |
hardillb
left a comment
hardillb
left a comment
There was a problem hiding this comment.
Comments added before I am OOO
| | Destination | Port | Purpose | | ||
| | --- | --- | --- | | ||
| | `registry.npmjs.org` | 443 | Installing Node-RED and node packages | | ||
| | `catalogue.nodered.org` | 443 | Default node catalogue used by the editor palette | |
There was a problem hiding this comment.
This is only required for the machines running the browser accessing the NR editor (for both hosted and remote), not from the FF install it's self.
There was a problem hiding this comment.
Fixed. Added a "Needed by" column and this row is now Editor browsers only, with a note that the editor fetches the catalogue directly and the platform does not. Confirmed in the editor client, palette-editor.js does the $.getJSON on the catalogue URL from the browser.
| | --- | --- | --- | | ||
| | `registry.npmjs.org` | 443 | Installing Node-RED and node packages | | ||
| | `catalogue.nodered.org` | 443 | Default node catalogue used by the editor palette | | ||
| | `registry-1.docker.io`, `auth.docker.io`, `production.cloudflare.docker.com` | 443 | Pulling FlowFuse and Node-RED container images, at install and at every upgrade | |
There was a problem hiding this comment.
Unless using a local Container registry/proxy
There was a problem hiding this comment.
Fixed. The row now ends with "Not needed if you pull the images from an internal registry or a pull-through proxy instead", and the restricted networks section lists an internal registry or pull-through proxy as an option.
|
|
||
| Only open these if the feature is in use. | ||
|
|
||
| | Destination | Port | Feature | Turn off with | |
There was a problem hiding this comment.
Turn off with
This doesn't feel the right way round
There was a problem hiding this comment.
Changed the column to "Required when", so each row states the condition that makes the destination necessary instead of how to switch it off. Config flags stay inside the cell where they help, for example blueprintImport.enabled.
| A hostname allowlist covers the large majority of Node-RED nodes, but not all of them. Some | ||
| packages download native builds at install time from arbitrary hosts, such as GitHub releases | ||
| or S3 buckets. Those cannot be listed up front. | ||
|
|
||
| If that is not acceptable, host the packages yourself and point FlowFuse at them: | ||
|
|
||
| - An internal npm registry and your own node catalogue. See | ||
| [3rd party npm registries](../user/custom-npm-packages.md#npm-registries). | ||
| - A mirror of the FlowFuse and Node-RED container images in your own registry. |
There was a problem hiding this comment.
That's a bit vague and hard to do in practice as you only find out they are pull native components when it fails and the only way to host them yourself is to either do proxy interception or build and host the nodes and their components yourself locally, this is a VERY big task.
There was a problem hiding this comment.
Rewrote that section. It now says a minority of packages fetch native components at install time from hosts that cannot be listed, that you only find out when an install fails, and that the ways round it are an intercepting proxy or building and hosting the packages and their components yourself, both a significant piece of work. The advice is to plan for a small number of nodes being unavailable rather than for full coverage.
Adds a 'Needed by' column so each destination says whether the platform, the Node-RED instances or the editor browsers has to reach it. The node catalogue is fetched by the editor client, not by the platform. Docker Hub is not needed when images come from an internal registry or a pull-through proxy. Replaces the 'Turn off with' column with 'Required when', so the table states the condition that makes a destination necessary rather than how to disable it. Restricted networks section is honest about the limit: a minority of packages fetch native components from hosts that cannot be listed, you find out when an install fails, and the only ways round it (intercepting proxy, or building and hosting the packages yourself) are a significant piece of work.
|
Note on the red check. "Test Documentation links" fails in It is not caused by this branch, which only adds and edits markdown under
So this needs a The job that validates the content of this PR, "Test Documentation with website" (site build plus |
|
@knolleary or @ppawlowski can you take a look here now that Ben is OOO |
|
Approved on the basis there could be finer details to add when we discover them - but lets get something merged so we can iterate as needed. |
| | `registry.npmjs.org` | 443 | Instances | Installing Node-RED and node packages | | ||
| | `catalogue.nodered.org` | 443 | Editor browsers | The node catalogue listed in the editor palette. The editor fetches it directly, the platform does not | | ||
| | `registry-1.docker.io`, `auth.docker.io`, `production.cloudflare.docker.com` | 443 | Platform | Pulling the FlowFuse and Node-RED container images, at install and at every upgrade. Not needed if you pull the images from an internal registry or a pull-through proxy instead | | ||
| | `ping.flowforge.com` | 443 | Platform | Anonymous usage telemetry | |
There was a problem hiding this comment.
Are we sure about this? Will a FlowFuse Platform on a self-hosted environment crash if access to the ping.flowforge.com is not possible?
Additionally, it should be ping.flowfuse.com. The old domain is used for legacy purposes and shouldn't be used in documents.
There was a problem hiding this comment.
Two separate things here.
Will it crash: no. The ping is a housekeeper task (forge/housekeeper/tasks/telemetryMetrics.js), scheduled once a day at a random time plus once ten seconds after startup, and the axios.post sits in a try/catch that logs Failed to send telemetry report. Blocking it costs you the report and nothing else. I have moved the row out of "Always required" into the conditional table and added a note saying exactly that, so nobody reads it as load-bearing.
The hostname: changed to ping.flowfuse.com as you asked, but flagging a mismatch with the code. The shipped default is still the old domain: telemetryMetrics.js:60 is app.config.telemetry.url || 'https://ping.flowforge.com/ping', and a code search across the org finds ping.flowfuse.com in no files and ping.flowforge.com in three, including docs/admin/telemetry.md:108. Both hostnames answer 200, but they resolve to different API Gateway deployments, so they are not aliases.
As the page now stands, an admin who allowlists only ping.flowfuse.com gets telemetry failing silently on every current release. Options as I see them:
- List both hostnames in the row, so the allowlist survives the switch.
- Move the default in code first, then the docs follow.
Which would you prefer? Happy to list both here and open a separate issue for the code default.
There was a problem hiding this comment.
@ppawlowski this needs your view again :)
There was a problem hiding this comment.
Any flowforge.com reference should not be used in publicly available documents.
There was a problem hiding this comment.
@ppawlowski did you see this:
As the page now stands, an admin who allowlists only ping.flowfuse.com gets telemetry failing silently on every current release. Options as I see them:
There was a problem hiding this comment.
My statement about avoiding the use of the old company name/domain name in the documentation remains.
There was a problem hiding this comment.
@ppawlowski Got it, merging. In that case, "elemetry failing silently", I'll take is a non-problem to be solved. If it actually is an issue, please open up an issue that we can solve separately.
ppawlowski
left a comment
ppawlowski
left a comment
There was a problem hiding this comment.
See my comments; none of them are blockers, though.
- introduction.md: replace the Networking requirements section with a one-sentence pointer, so the overview page carries no detail of its own. - telemetry: move the row out of "Always required" into the conditional table and state that a blocked post is only logged, since the ping runs as a background task and does not stop the platform. - telemetry: use ping.flowfuse.com rather than the legacy domain. - GitOps: split the single GitHub row into GitHub, Azure DevOps and any other HTTPS Git server, matching the three supported backends.
|
@dgatti0213 can you have a look here as well. See if it aligns from your side as well |
…not just install For self-hosted installs, "FlowFuse installed" is not the same as a ready environment. If the environment can't reach the hosts FlowFuse needs to install and update nodes/packages, the PoV stalls the first time someone adds a node — a recent PoV lost a week to exactly this. Strengthen gate #5 in both the Solution "What the SE produces" list and the Pre-PoV checklist: the outbound access must be filed *and proven* during Solution, and links to the Networking requirements docs page for the host list to hand the customer's network team. Depends on FlowFuse/flowfuse#8354, which adds /docs/install/networking-requirements — keep this PR in draft until that merges (the link 404s until then). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KT4u2XgENWkw2Rm6oEXFXx
6 participants
Adds an outbound egress list for self-hosted installs. Comes from a self-hosted enterprise renewal on a narrow-egress OT network that needs to file one change-controlled firewall request: https://github.com/FlowFuse/accounts/issues/128. Sales reports it is a common question.
Today there is no self-hosted egress list in the docs. The only list is on the Device Agent overview page, which covers agent to Cloud traffic, so a self-hoster behind a firewall reads Cloud-only endpoints as authoritative for their install.
Where it lives
docs/install/networking-requirements.md, in the Installing FlowFuse nav group alongside DNS Setup and Configuring FlowFuse. It is reference material (what is required), not a how-to, so it is a flat table with conditions rather than a walkthrough. Linked from:Open questions for review
registry.npmjs.com, which should be.org.