Skip to content

installation.md

Latest commit

 

History

History
193 lines (135 loc) · 5.08 KB

installation.md

File metadata and controls

193 lines (135 loc) · 5.08 KB

Detailed Installation

This guide includes all installation steps and verification steps.

Prerequisites

  • Node-RED (v3.0+)
  • Node.js (v18+)
  • npm (comes with Node.js)
  • Oracle Instant Client 23c (required only when db-connection Driver Mode is set to Thick)

1.1 Clone the Repository

Navigate to your Node-RED user directory (typically ~/.node-red) and clone:

HTTPS

git clone https://github.com/oracle-samples/node-red-nodes.git

SSH

git clone git@github.com:oracle-samples/node-red-nodes.git

GitHub CLI

gh repo clone oracle-samples/node-red-nodes

1.2 Install Dependencies

Install required npm packages inside your Node-RED user directory (~/.node-red):

cd ~/.node-red

# DB nodes
npm install oracledb

# SCM nodes
npm install axios
npm install https-proxy-agent

# OCI nodes (Notifications, Logging, Log Analytics, Object Storage, IoT Send Command)
npm install oci-sdk

# IoT nodes (Telemetry, Command)
npm install mqtt

Install Oracle Instant Client (23c) when using DB nodes in Thick mode:

sudo dnf install oracle-instantclient-release-el8
sudo dnf install oracle-instantclient-basic
sudo dnf install oracle-instantclient-sqlplus

NOTE: Oracle Linux typically installs Instant Client into /usr/lib/oracle/23/client64/lib by default. To use a different path, set the ORACLE_CLIENT_LIB environment variable before starting Node-RED:

export ORACLE_CLIENT_LIB=/path/to/your/instantclient

If ORACLE_CLIENT_LIB is not set, the driver falls back to node-oracledb platform default library lookup (for example, PATH on Windows).

If all DB connections use Driver Mode Thin, Oracle Instant Client is not required.

Native Install Reliability (oracledb)

oracledb is a native module, so build/runtime consistency matters in CI and container images.

  • Keep the same Node.js major/minor version between image build and runtime.
  • Install dependencies inside the final runtime image/layer (avoid copying node_modules across different OS images).
  • If you upgrade Node.js after installing modules, run npm rebuild oracledb.
  • For Thick mode, ensure Instant Client shared libraries are present at runtime (LD_LIBRARY_PATH or ORACLE_CLIENT_LIB).
  • Prefer Thin mode when Oracle Advanced Security features and wallet/TNS requirements do not require Thick mode.

1.3 Install from Local .tgz in Palette Manager

When installing from a local file in Node-RED Palette Manager, you must use an npm pack tarball that you generate yourself from this repo.

Palette upload expects the archive to contain:

package/package.json
package/...

GitHub source/release tarballs are not directly uploadable because they typically contain:

node-red-nodes-<version>/...

If you upload a source tarball, Node-RED may fail with errors like Module not found.

Required for Palette upload: create install artifact with npm pack

From the repository root:

npm pack

This creates a file like node-red-nodes-0.4.1.tgz. Upload that file in Palette Manager:

  1. Open Node-RED editor.
  2. Menu → Manage palette → Install.
  3. Choose local file upload.
  4. Select the .tgz generated by npm pack.

Recovery: you only have a source/release tarball

If your downloaded archive is a source tarball, re-pack it with npm first.

Windows (PowerShell):

cd $env:TEMP
tar -xf C:\Users\<you>\Downloads\node-red-nodes-0.4.1.tgz
cd .\node-red-nodes-0.4.1
npm pack

Windows (cmd):

cd /d %TEMP%
tar -xf C:\Users\<you>\Downloads\node-red-nodes-0.4.1.tgz
cd node-red-nodes-0.4.1
npm pack

Linux/macOS:

cd /tmp
tar -xf ~/Downloads/node-red-nodes-0.4.1.tgz
cd node-red-nodes-0.4.1
npm pack

Upload the new npm-packed .tgz file via Palette Manager. This npm pack step is required for editor import.

1.4 Private Subnet Installation (Proxy + Registry Setup)

When running Node-RED on a private subnet not accessible to the internet, the npm proxy and registry must be configured to access external packages.

Set npm registry:

npm config set registry https://internal-npm-registry-link

Disable strict SSL:

npm config set strict-ssl false

Configure npm proxy:

npm config set proxy http://user-proxy-host:port
npm config set https-proxy http://user-proxy-host:port

1.5 Verify Installation

  1. Restart Node-RED:
sudo systemctl restart node-red

  1. Confirm the nodes appear in the palette under their categories: oracle db, oracle fusion scm, and oci.

  2. Import an example JSON flow and deploy it:

1.6 Which Dependencies Are Needed?

Not all dependencies are required. Install only what you need:

If you're using... Install
DB nodes only oracledb (+ Oracle Instant Client when Driver Mode is Thick)
SCM nodes only axios, https-proxy-agent
OCI Notifications, Logging, Log Analytics, Object Storage, or IoT Send Command oci-sdk
IoT Telemetry or IoT Command mqtt
Everything All of the above