Skip to main content

setting up a Custom Certificate

By default, the @opcua/for-node-red package generates a self-signed certificate for each OPC UA Client connection. However, in some scenarios, you may want to use a custom certificate and private key for enhanced security or compliance with organizational policies.

We provide a single PKI location shared with all Client connections.

PKI location​

The PKI lives inside your Node-RED user directory (RED.settings.userDir), under opcua-for-node-red/PKI. This means:

  • Bare metal: ~/.node-red/opcua-for-node-red/PKI (or whatever you passed to node-red --userDir).
  • Official Docker image (nodered/node-red): /data/opcua-for-node-red/PKI — persisted by the standard /data volume alongside flows.json.
  • FlowFuse: <instance working directory>/opcua-for-flow-fuse/PKI.

Putting the PKI under userDir ensures that whatever you already do to back up your flows also backs up your trust store and private keys.

Docker — persisting the PKI​

A single volume on /data covers both your flows and the PKI:

services:
  node-red:
    image: nodered/node-red:latest
    ports:
      - "1880:1880"
    volumes:
      - node_red_data:/data

volumes:
  node_red_data:

After this, certificates trusted from the certificate-manager UI survive docker compose down / up cycles and image upgrades.

Overriding the PKI location​

If you need the PKI to live somewhere other than userDir (for example on a separate encrypted volume), set the STERFIVE_CONTAINER_CONFIG_FOLDER environment variable. The PKI will then live under ${STERFIVE_CONTAINER_CONFIG_FOLDER}/opcua-for-node-red/PKI.

services:
  node-red:
    image: nodered/node-red:latest
    environment:
      - STERFIVE_CONTAINER_CONFIG_FOLDER=/sterfive
    volumes:
      - node_red_data:/data
      - sterfive_data:/sterfive

volumes:
  node_red_data:
  sterfive_data:

Migrating from earlier versions​

Previous versions stored the PKI under the OS user-config directory (resolved by the env-paths library):

  • Linux: ~/.config/opcua-for-node-red-nodejs/PKI
  • macOS: ~/Library/Preferences/opcua-for-node-red-nodejs/PKI
  • Windows: %APPDATA%\opcua-for-node-red-nodejs\Config\PKI

When the package starts up and detects a non-empty PKI at the legacy location, it logs a warning. To preserve your trusted certificates, copy the contents of the legacy folder into the new userDir/opcua-for-node-red/PKI and restart Node-RED. (No automatic migration is performed because PKI material is sensitive and we want you in control.)

Alternatively, set STERFIVE_CONTAINER_CONFIG_FOLDER to point back at the legacy parent directory to keep the previous behaviour.

for X509 user certificates​

User certificates live in the same PKI tree described above (<userDir>/opcua-for-node-red/PKI).