Initial commit: Nextcloud Node-RED Docker image and custom nodes
This commit is contained in:
newkle3r
@@ -0,0 +1,177 @@
|
||||
# Nextcloud Node-RED Integration
|
||||
|
||||
Custom [Node-RED](https://nodered.org/) Docker image with **16 palette nodes** that call Nextcloud APIs (OCS, WebDAV, and app-specific endpoints), plus a companion [Nextcloud app](../nodered-embed/) 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](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)
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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](../nodered-embed/README.md).
|
||||
|
||||
## 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](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:
|
||||
|
||||
```bash
|
||||
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** ):
|
||||
|
||||
```bash
|
||||
docker rm -f nextcloud-node-red
|
||||
docker volume rm node-red-data
|
||||
docker run -d ... # same run command as above
|
||||
```
|
||||
|
||||
See [docs/TROUBLESHOOTING.md](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](docs/ARCHITECTURE.md)
|
||||
- [Deployment guide](docs/DEPLOYMENT.md)
|
||||
- [Node reference](docs/NODES.md)
|
||||
- [Troubleshooting](docs/TROUBLESHOOTING.md)
|
||||
- [Nextcloud embed app](../nodered-embed/README.md)
|
||||
|
||||
## License
|
||||
|
||||
AGPL-3.0 — see [LICENSE](LICENSE).
|
||||
Reference in New Issue
Block a user