Add guidance for trusting custom CA certificates in Docker deployments

[dgatti0213]

Description

Problem
Our self-hosted Docker install docs have no guidance on how to configure trust for custom or self-signed CA certificates. This is a real gap for on-prem and air-gapped deployments where customers are connecting Node-RED to internally TLS-secured services.
A common real-world example: a customer running RabbitMQ with TLS enabled using a self-signed CA. By default, Node-RED instances spun up by FlowFuse will reject connections to that broker because they have no knowledge of the private CA. There is currently no documentation explaining how to solve this.

Specifically there is no guidance on:
Injecting a custom CA into the forge container via NODE_EXTRA_CA_CERTS
Whether and how DOCKER_DRIVER_PRIVATE_CA_PATH propagates CA trust to spawned Node-RED instance containers
Recommended volume mount structure for cert files on a Linux host
Any additional steps required for full end-to-end CA trust in an air-gapped deployment

What exists today
The Docker install docs cover DNS setup, project stacks, and platform config but have no TLS or certificate trust section. Neither NODE_EXTRA_CA_CERTS nor DOCKER_DRIVER_PRIVATE_CA_PATH are mentioned anywhere in the docs. There is also no doc covering air-gapped Linux on-prem deployments as a scenario at all.

Compose file for review
https://drive.google.com/file/d/1O_Ie_b4FJN7w9MW4nc4I3pURNJBg3IHa/view?usp=sharing

Questions for engineering before writing this doc

1. What is the officially supported pattern for injecting a private CA into the forge container?
2. Does DOCKER_DRIVER_PRIVATE_CA_PATH propagate CA trust to spawned Node-RED instance containers?
3. What value should it be set to?
4. Is there anything else required for full CA trust end-to-end in an air-gapped Docker deployment?

Proposed location
New section under Installing FlowFuse > Docker install — "TLS & Custom Certificates" or "Using a Private CA"

[ppawlowski]

https://flowfuse.com/docs/install/docker/#custom-tls-certificate

[hardillb]

DOCKER_DRIVER_PRIVATE_CA_PATH is just for Hosted Node-RED instances

If the forge app needs to trust the CA then you also need to mount same file as pointed to by DOCKER_DRIVER_PRIVATE_CA_PATH in forge service and add NODE_EXTRA_CA_CERTS env var that points to the mount point to the envs section.

assumes DOCKER_DRIVER_PRIVATE_CA_PATH = /opt/flowfuse/ca-chain.pem

forge:
    image: "flowfuse/forge-docker:2.27.1"
    networks: 
      - flowforge
    restart: always
    environment:
      - "VIRTUAL_HOST=${APPLICATION_DOMAIN:-forge.${DOMAIN}}"
      - "LETSENCRYPT_HOST=${APPLICATION_DOMAIN:-forge.${DOMAIN}}"
      - "NODE_EXTA_CA_CERTS=/usr/local/share/ca-certificates/ca-chain.pem" << new
    configs:
      - source: flowfuse
        target: /usr/src/forge/etc/flowforge.yml
    volumes:
      - "/var/run/docker.sock:/tmp/docker.sock"
      - flowfuse-persistent-storage:/opt/persistent-storage
      - /opt/flowfuse/ca-chain.pem:/usr/local/share/ca-certificates/ca-chain.pem <<< new
    depends_on:

[ppawlowski]

The docker-compose file contains solution (commented out) mentioned by @hardillb

• https://github.com/FlowFuse/docker-compose/blob/main/docker-compose.yml#L523
• https://github.com/FlowFuse/docker-compose/blob/main/docker-compose.yml#L530

[dgatti0213]

Sorry I missed that DOCKER_DRIVER_PRIVATE_CA_PATH was already documented. The actual docs gap seems to be NODE_EXTRA_CA_CERTS on the forge container side.

Does the same approach need to be applied for remote instances as well, or is that handled differently?

[hardillb]

Remote instances need NODE_EXTRA_CA_CERTS setting as well