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

docs/DEPLOYMENT.md

@@ -0,0 +1,138 @@
+# Deployment guide
+
+## Target layout (example)
+
+| Service | Host | Port |
+|---------|------|------|
+| Nextcloud | `https://cloud.example.com` | 443 |
+| Node-RED | same VM, `192.168.1.26` | 1880 |
+
+Node-RED must be reachable from users’ browsers (for the iframe) and from itself (for API calls to Nextcloud).
+
+## 1. Deploy Node-RED (Docker)
+
+On the Ubuntu VM:
+
+```bash
+cd /home/ncadmin/nextcloud-node-red   # or your clone path
+git pull                              # get latest nodes + entrypoint
+
+docker compose build --no-cache
+docker compose up -d
+```
+
+Or without Compose:
+
+```bash
+docker build --no-cache -t nextcloud-node-red:latest .
+docker rm -f nextcloud-node-red 2>/dev/null || true
+docker run -d \
+  --name nextcloud-node-red \
+  --network host \
+  -v node-red-data:/data \
+  --restart unless-stopped \
+  nextcloud-node-red:latest
+```
+
+Verify:
+
+```bash
+docker logs -n 30 nextcloud-node-red
+# Expect: [entrypoint] Installing nextcloud nodes...
+#         User directory : /data
+
+curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:1880/
+# Expect: 200
+```
+
+### Nextcloud URL in config nodes
+
+Inside Node-RED, set **Nextcloud URL** to something the **container** can resolve:
+
+| Scenario | URL |
+|----------|-----|
+| Nextcloud on same VM, host networking | `https://127.0.0.1` or `https://cloud.example.com` |
+| Nextcloud on another host | `https://192.168.1.x` or public hostname |
+
+Test from inside the container:
+
+```bash
+docker exec nextcloud-node-red wget -qO- --no-check-certificate \
+  https://cloud.example.com/status.php
+```
+
+## 2. Deploy Nextcloud app
+
+```bash
+sudo cp -r nodered-embed /var/www/nextcloud/apps/
+sudo chown -R www-data:www-data /var/www/nextcloud/apps/nodered-embed
+sudo -u www-data php /var/www/nextcloud/occ app:enable nodered_embed
+```
+
+Configure in **Settings → Administration → Node-RED Embed**:
+
+- **Node-RED URL:** `http://192.168.1.26:1880` (use the address clients use; not `127.0.0.1` unless only local admins use it)
+
+## 3. Reverse proxy (optional)
+
+If Node-RED is behind nginx/Apache with TLS:
+
+- Ensure the proxy does **not** send `X-Frame-Options: DENY` (blocks iframe embed).
+- Point Nextcloud admin URL to the public HTTPS URL, e.g. `https://nodered.example.com`.
+
+If Nextcloud is behind a proxy, CSP host extraction uses the hostname from `nodered_url` — use the same hostname users load in the iframe.
+
+## 4. Firewall
+
+Allow **1880/tcp** (or your mapped port) from Nextcloud users’ networks if they open the embed from LAN/VPN.
+
+## 5. Updating custom nodes
+
+After changing files under `nodes/nextcloud-ocs/`:
+
+```bash
+docker builder prune -af          # optional, avoids stale COPY cache
+docker build --no-cache -t nextcloud-node-red:latest .
+docker restart nextcloud-node-red
+```
+
+Confirm version:
+
+```bash
+docker exec nextcloud-node-red cat \
+  /data/node_modules/node-red-contrib-nextcloud-ocs/package.json | grep version
+```
+
+### When to delete the volume
+
+Delete `node-red-data` only if:
+
+- Palette shows wrong/old nodes after rebuild, or
+- Entrypoint copy failed with permission errors from old root-owned files
+
+**Warning:** removes all flows and credentials.
+
+```bash
+docker rm -f nextcloud-node-red
+docker volume rm node-red-data
+docker compose up -d
+```
+
+## 6. Backup
+
+Back up the Docker volume:
+
+```bash
+docker run --rm -v node-red-data:/data -v $(pwd):/backup alpine \
+  tar czf /backup/node-red-data-backup.tar.gz -C /data .
+```
+
+Restore by extracting into a new volume before first start.
+
+## 7. Production checklist
+
+- [ ] Set `credentialSecret` in Node-RED settings (`/data/settings.js`)
+- [ ] Use app passwords with minimal needed scopes
+- [ ] TLS on Nextcloud; consider TLS on Node-RED if exposed beyond LAN
+- [ ] Restrict who can access Node-RED (firewall / VPN / admin-only NC group)
+- [ ] Enable Nextcloud app only for trusted admins if flows can access sensitive data