nextcloud-nodered-ocs-api/README.md

Nextcloud Node-RED Integration

Custom Node-RED Docker image with 16 palette nodes that call Nextcloud APIs (OCS, WebDAV, and app-specific endpoints), plus a companion Nextcloud app that embeds the editor in the Nextcloud UI.

Repositories

Directory	Purpose
nextcloud-node-red/ (this repo)	Docker image + node-red-contrib-nextcloud-ocs custom nodes
nodered-embed/	Nextcloud PHP app — iframe embed, CSP, admin settings

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  Nextcloud (https://your-cloud.example)                         │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  nodered_embed app  →  iframe  →  Node-RED :1880          │  │
│  │  CSPListener allows frame-src / frame-ancestors           │  │
│  └───────────────────────────────────────────────────────────┘  │
└───────────────────────────────┬─────────────────────────────────┘
                                │ Basic Auth (app password)
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│  Docker: nextcloud-node-red                                     │
│  userDir: /data  →  /data/node_modules/node-red-contrib-...     │
│  entrypoint copies nodes from /opt at container start          │
└─────────────────────────────────────────────────────────────────┘

See docs/ARCHITECTURE.md for implementation details.

Requirements

• Linux host (or VM) with Docker
• Nextcloud 25+ (tested with modern OCS v2 APIs)
• network_mode: host on Linux so the container can reach Nextcloud on the same machine (avoids 127.0.0.1 / /etc/hosts issues inside the container)
• Nextcloud app password per user (Settings → Security → Devices & sessions)

Quick start

Docker Compose (recommended)

git clone <your-repo-url> nextcloud-node-red
cd nextcloud-node-red
docker compose up -d --build

Open http://localhost:1880 (or the host IP if remote).

Manual Docker

docker build -t nextcloud-node-red:latest .
docker run -d \
  --name nextcloud-node-red \
  --network host \
  -v node-red-data:/data \
  --restart unless-stopped \
  nextcloud-node-red:latest

Important: Use --network host on Linux. Without it, https://localhost or your server hostname may resolve incorrectly inside the container.

Nextcloud embed app

Copy nodered-embed/ to your Nextcloud apps directory and enable it:

cp -r nodered-embed /var/www/nextcloud/apps/
sudo -u www-data php /var/www/nextcloud/occ app:enable nodered_embed

In Administration → Node-RED Embed, set the Node-RED URL (e.g. http://192.168.1.26:1880). See nodered-embed README.

First-time setup in Node-RED

1. Drag a nextcloud config node onto the canvas (any Nextcloud node will prompt you).
2. Set Nextcloud URL to your instance, e.g. https://cloud.example.com (no trailing slash).
3. Set Username and App password (not your login password).
4. Deploy and test with ocs-api → operation GET on /ocs/v2.php/cloud/user.

Custom nodes (overview)

Node	Palette category	Description
nextcloud-config	config	Shared credentials (URL, user, app password)
ocs-api	nextcloud	Generic OCS HTTP (any path/method)
collectives	nextcloud	Collectives app (~80 operations)
file-operations	nextcloud	WebDAV files + OCS sharing
mail	nextcloud	Mail app
tables	nextcloud	Tables app
talk	nextcloud	Talk (Spreed)
webhooks	nextcloud	Webhook Listeners
dashboard	nextcloud	Dashboard widgets
dav	nextcloud	DAV (direct links, out-of-office)
core	nextcloud	Core OCS (capabilities, search, tasks, …)
oauth2	nextcloud	OAuth2 clients
provisioning	nextcloud	User/group provisioning API
filesharing	nextcloud	File sharing OCS
userstatus	nextcloud	User status
settings	nextcloud	User/admin settings

Full operation lists: docs/NODES.md.

Runtime overrides

Most nodes accept msg overrides:

Property	Effect
msg.operation	Operation id (e.g. collective:list)
msg.endpoint	ocs-api only — API path
msg.method	ocs-api only — HTTP method
msg.body	JSON request body
msg.headers	Extra HTTP headers
Path params	msg.collectiveId, msg.pageId, msg.userId, etc.

Updating nodes after code changes

The image bakes nodes under /opt/nextcloud-nodes/. At every container start, entrypoint.sh copies them into the /data volume (Node-RED userDir). To pick up new node files:

docker build --no-cache -t nextcloud-node-red:latest .
docker rm -f nextcloud-node-red
docker run -d --name nextcloud-node-red --network host \
  -v node-red-data:/data --restart unless-stopped nextcloud-node-red:latest

If the palette still shows an old version, remove the volume ( deletes flows ):

docker rm -f nextcloud-node-red
docker volume rm node-red-data
docker run -d ...  # same run command as above

See docs/TROUBLESHOOTING.md.

Project layout

nextcloud-node-red/
├── Dockerfile              # Base: nodered/node-red, COPY nodes + entrypoint
├── entrypoint.sh           # Install nodes into /data, start node-red
├── docker-compose.yml      # host network + named volume
├── nodes/nextcloud-ocs/    # node-red-contrib-nextcloud-ocs package
│   ├── package.json        # node-red.nodes registry (16 nodes)
│   ├── nextcloud-config.js / .html
│   ├── ocs-api.js / .html
│   └── …                   # one .js + .html pair per node
└── docs/
    ├── ARCHITECTURE.md
    ├── DEPLOYMENT.md
    ├── NODES.md
    └── TROUBLESHOOTING.md

Security notes

• Credentials are stored in Node-RED’s encrypted credentials store; set credentialSecret in /data/settings.js for production.
• Nodes use Basic Auth with app passwords; scope passwords per automation.
• rejectUnauthorized: false is used for HTTPS to allow self-signed certs — tighten for production if you use proper TLS.
• The Nextcloud embed iframe uses a restrictive sandbox attribute; adjust only if you need additional browser capabilities.

Documentation

• Architecture
• Deployment guide
• Node reference
• Troubleshooting
• Nextcloud embed app

License

AGPL-3.0 — see LICENSE.