docs: add networking requirements page for self-hosted installs - #8354
docs: add networking requirements page for self-hosted installs#8354dimitrieh wants to merge 3 commits into
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 |
3 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.