Initial commit: Nextcloud Node-RED Docker image and custom nodes

2026-05-15 14:50:48 +02:00
commit fd7cc695f7
44 changed files with 3936 additions and 0 deletions
@@ -0,0 +1,81 @@
+# Architecture
+
+## Two components
+
+### 1. `nextcloud-node-red` (Docker + nodes)
+
+A thin wrapper around the official [`nodered/node-red`](https://hub.docker.com/r/nodered/node-red) image:
+
+1. **Build time:** `nodes/nextcloud-ocs/` is copied to `/opt/nextcloud-nodes/node-red-contrib-nextcloud-ocs`.
+2. **Run time:** `entrypoint.sh` runs as container `ENTRYPOINT`, copies that tree into `/data/node_modules/node-red-contrib-nextcloud-ocs`, then starts `node-red --userDir /data`.
+
+Node-RED discovers contrib nodes from `{userDir}/node_modules/*/package.json` → `node-red.nodes` map.
+
+### 2. `nodered-embed` (Nextcloud app)
+
+PHP app registered as `nodered_embed`:
+
+- **Navigation** entry opens a full-page iframe to the configured Node-RED URL.
+- **CSPListener** relaxes Content-Security-Policy so Nextcloud may embed Node-RED (`frame-src`) and Node-RED may embed Nextcloud pages if needed (`frame-ancestors`).
+- **Admin settings** store `nodered_url`, optional Docker container name, and a Docker-management flag (UI only for now).
+
+## Node implementation pattern
+
+Each functional node follows the same structure:
+
+```
+collectives.js     → OPERATIONS hash (operationId → method, path, body fields)
+collectives.html   → Editor UI, dropdown of operations, config node picker
+nextcloud-config.js → Credential node (baseUrl, username, password)
+```
+
+On input:
+
+1. Resolve `msg.operation` or the configured default operation.
+2. Substitute path placeholders (`{id}`, `{collectiveId}`, …) from config + `msg.*`.
+3. Build query string and JSON body from configured fields + `msg` overrides.
+4. HTTP request with `OCS-APIRequest: true`, `Accept: application/json`, Basic Auth.
+5. Parse JSON into `msg.payload`, set `msg.statusCode`, `node.send(msg)`.
+
+**ocs-api** is the escape hatch: you supply any OCS path and method without adding a new operation to the hash.
+
+## Data persistence
+
+| Path | Contents |
+|------|----------|
+| `/data/flows.json` | Flows (Docker volume `node-red-data`) |
+| `/data/flows_cred.json` | Encrypted credentials |
+| `/data/node_modules/node-red-contrib-nextcloud-ocs/` | Copy of custom nodes (refreshed on each start) |
+
+The named volume **masks** anything copied into `/data` at image build time. That is why the entrypoint always re-copies from `/opt`.
+
+## Network
+
+```
+Node-RED container (--network host)
+    → https://cloud.example.com  (same host or LAN)
+```
+
+On Ubuntu, a bridge network often breaks `localhost` / hostname resolution (`127.0.1.1` in `/etc/hosts`). Host networking avoids that for co-located Nextcloud + Node-RED.
+
+## Authentication flow
+
+```
+Editor: nextcloud-config node
+    → stored in flows_cred.json (encrypted)
+
+Runtime: each API node
+    → RED.nodes.getNode(config.nextcloud)
+    → credentials.username + credentials.password
+    → Authorization: Basic base64(user:app-password)
+```
+
+Use **app passwords**, not the account login password.
+
+## Versioning
+
+Package version in `nodes/nextcloud-ocs/package.json` (e.g. `0.8.0`) should be bumped when adding nodes or breaking operation ids. After deploy, verify inside the container:
+
+```bash
+docker exec nextcloud-node-red cat /data/node_modules/node-red-contrib-nextcloud-ocs/package.json
+```