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

docs/TROUBLESHOOTING.md

@@ -0,0 +1,166 @@
+# Troubleshooting
+
+## Nodes missing from palette
+
+### Symptom
+
+Node-RED runs but Nextcloud nodes do not appear under **Manage palette → Nodes**.
+
+### Checks
+
+1. **Entrypoint ran**
+
+   ```bash
+   docker logs nextcloud-node-red 2>&1 | head -20
+   ```
+
+   Expect:
+
+   ```
+   [entrypoint] Installing nextcloud nodes into /data...
+   [entrypoint] Source: /opt/nextcloud-nodes/node-red-contrib-nextcloud-ocs
+   [entrypoint] Target: /data/node_modules/node-red-contrib-nextcloud-ocs
+   ```
+
+   If you only see the Node-RED banner with no `[entrypoint]` lines, the image may still use `CMD` instead of `ENTRYPOINT ["/entrypoint.sh"]` — rebuild from current `Dockerfile`.
+
+2. **Module installed in userDir**
+
+   ```bash
+   docker exec nextcloud-node-red ls /data/node_modules/node-red-contrib-nextcloud-ocs
+   docker exec nextcloud-node-red cat /data/node_modules/node-red-contrib-nextcloud-ocs/package.json
+   ```
+
+3. **User directory**
+
+   Logs must show `User directory : /data`. If it shows `/usr/src/node-red/.node-red/`, entrypoint did not start Node-RED with `--userDir /data`.
+
+4. **Stale volume (old package version)**
+
+   Compare `/opt` vs `/data`:
+
+   ```bash
+   docker exec nextcloud-node-red sh -c \
+     'grep version /opt/nextcloud-nodes/node-red-contrib-nextcloud-ocs/package.json; \
+      grep version /data/node_modules/node-red-contrib-nextcloud-ocs/package.json'
+   ```
+
+   If `/opt` is newer, restart should copy on boot. If `/data` stays old, remove volume (loses flows):
+
+   ```bash
+   docker rm -f nextcloud-node-red
+   docker volume rm node-red-data
+   docker run -d --name nextcloud-node-red --network host \
+     -v node-red-data:/data --restart unless-stopped nextcloud-node-red:latest
+   ```
+
+5. **Browser cache**
+
+   Hard refresh (Ctrl+F5) or open Node-RED in a private window.
+
+---
+
+## Container restart loop
+
+### Symptom
+
+`docker ps` shows `Restarting`; logs repeat entrypoint lines.
+
+### Cause
+
+Old `entrypoint.sh` tried to copy missing `settings.js`:
+
+```
+cp: can't stat '/usr/src/node-red/.node-red/settings.js': No such file or directory
+```
+
+### Fix
+
+Use current `entrypoint.sh` (starts `node-red --userDir /data` only). Rebuild:
+
+```bash
+docker build --no-cache -t nextcloud-node-red:latest .
+```
+
+---
+
+## `No Nextcloud configuration node selected`
+
+Flow nodes reference a deleted or unconfigured **nextcloud-config** node. Open each red Nextcloud node and re-select the config node, then Deploy.
+
+---
+
+## API errors / connection refused
+
+| Issue | Fix |
+|-------|-----|
+| `ECONNREFUSED` to localhost | Use `--network host` or use LAN IP / hostname, not `127.0.0.1` from bridge network |
+| SSL errors | Self-signed: nodes set `rejectUnauthorized: false`; or install proper certs |
+| 401 Unauthorized | Use **app password**, correct username |
+| 404 on OCS path | App not installed/enabled on Nextcloud (Collectives, Talk, etc.) |
+
+Test from container:
+
+```bash
+docker exec nextcloud-node-red wget -qO- --header="OCS-APIRequest: true" \
+  --user='USER:APP_PASSWORD' \
+  https://cloud.example.com/ocs/v2.php/cloud/user
+```
+
+---
+
+## Docker build shows old files
+
+Build context must include updated `nodes/nextcloud-ocs/`:
+
+```bash
+grep version nodes/nextcloud-ocs/package.json   # on host before build
+docker build --no-cache -t nextcloud-node-red:latest .
+```
+
+`docker builder prune -af` clears COPY layer cache.
+
+---
+
+## Nextcloud iframe blank
+
+1. Browser DevTools → Console: CSP violations.
+2. Confirm **nodered_embed** is enabled and admin URL matches iframe target host.
+3. `CSPListener` adds `frame-src` for the hostname from `nodered_url`.
+4. Reverse proxy must not set `X-Frame-Options: DENY` on Node-RED.
+
+```bash
+curl -I https://cloud.example.com | grep -i frame
+curl -I http://192.168.1.26:1880 | grep -i frame
+```
+
+---
+
+## Permission denied on entrypoint copy
+
+Old files in volume owned by root. Fix:
+
+```bash
+docker rm -f nextcloud-node-red
+docker volume rm node-red-data
+# recreate container
+```
+
+Or fix ownership once:
+
+```bash
+docker exec -u root nextcloud-node-red chown -R node-red:node-red /data
+```
+
+---
+
+## Verify node discovery manually
+
+```bash
+docker exec nextcloud-node-red node -e "
+  const p=require('/data/node_modules/node-red-contrib-nextcloud-ocs/package.json');
+  console.log(p.version, Object.keys(p['node-red'].nodes).length, 'nodes');
+"
+```
+
+Expected: version from `package.json` and **16** node types.