nextcloud-nodered-ocs-api/README.md

# 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).