n3wk/nextcloud-collabora-nodered
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial release v1.0.0 — Nextcloud Collabora Node-RED sidecar

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Hannes Ahlin
2026-08-22 14:56:38 +02:00
commit d2f70ee2a7
38 changed files with 2239 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/AGENT-MANUAL.md
+203
View File
@@ -0,0 +1,203 @@
# Assistentmanual — Nextcloud Office + Collabora Node-RED
**Version 1.0 — 22 augusti 2026**
Gäller sidecaren `nextcloud-collabora-nodered` mot Nextcloud på `cloud.hannesahlin.se` och Collabora CODE 26.04.x (container `code`, `127.0.0.1:9980`). Odds-scraper ignoreras.
Du är en **flödesagent**. Du skapar och modifierar Node-RED-flöden, inte LibreOffice-makron i webbläsaren. All fil-I/O går via Nextcloud WebDAV eller OCS. All dokumentmotor går via CODE REST.
---
## 1. Uppdrag och gränser
1. Använd **app-lösenord** i `nc-collab-config`. Aldrig vanligt kontolösen.
2. Skriv **inte över original**. Standardmål: `/Dokument/OfficeOut/`.
3. `postMessage`-API och `CallPythonScript` är iframe/webbläsare. **Inte Node-RED.**
4. WOPI PutFile är CODE:s jobb mot Nextcloud. Agenten använder **WebDAV PUT**.
5. Exponera inte port 9980 utanför loopback.
6. Rör inte odds-scraper eller Gitea-databaslösen i flöden.
---
## 2. Miljö
| Nyckel | Värde |
|--------|-------|
| Nextcloud | `https://cloud.hannesahlin.se` (host 192.168.1.26) |
| CODE | container `code`, `127.0.0.1:9980`, aliasgroup `https://cloud.hannesahlin.se:443` |
| Befintlig Node-RED | `nextcloud-node-red` `:1880` (OCS-noder) |
| Ny sidecar | `nextcloud-collabora-nodered` `:1881` |
| Intern CODE-URL från sidecar | `http://host.docker.internal:9980` |
| Auth | Basic + Nextcloud app-lösenord, header `OCS-APIRequest: true` |
---
## 3. Kartan Nextcloud → Collabora
| Nextcloud | Collabora-yta | Nod |
|-----------|-----------------|-----|
| WebDAV GET fil | input till convert/extract/transform | convert, extract, transform, bridge |
| WebDAV PUT | spara PDF/DOCX/PNG | samma + `destNcPath` |
| files convert OCS | samma motor via richdocuments | nc-office `files:convert` |
| richdocuments mallar | convert-to `template=` eller NC create-from-template | nc-office `templates:*` |
| template fields | content controls | extractFields / fillFields / transform |
| file versions | compare= på convert-to | bridge `compareVersionsPdf` |
| fileId + direct token | WOPISrc + editor iframe | nc-office `document:direct`, wopi `buildEditor` |
| assets API | linking / insert graphic URL | assets:create + klient postMessage |
| shares | public edit URL | document:public |
| preview | convert-to png | ncFileToPng |
| HTML/MD | convert-to office | htmlToOffice |
Talk, Tables, Mail, Collectives ska **konsumera resultatet** (dela PDF, bifoga, lägg i collective) — de ersätter inte WOPI-host.
---
## 4. Noder och msg-kontrakt
### 4.1 nc-collab-config
En instans per miljö. Fält: `nextcloudUrl`, `collaboraUrl`, ev. `collaboraPublicUrl`, `username`, app-lösen, `verifyTls` (false i labb-VM tills certkedjan är ren).
### 4.2 Gemensamma msg-fält
| Fält | Betydelse |
|------|-----------|
| `ncPath` | Sökväg i användarens filrot, t.ex. `/Mallar/avtal.docx` |
| `fileId` | Numeriskt Nextcloud-fileid |
| `payload` | Buffer eller text om källan inte ligger i NC |
| `format` | pdf \| png \| docx \| odt \| html \| txt \| xlsx \| pptx … |
| `destNcPath` / `destFolder` / `destName` | Var resultatet skrivs |
| `transform` / `fields` | JSON för struktur-API eller mallfält |
| `templateNcPath` / `compareNcPath` | Extra filer till convert-to |
| `operation` | Överstyr dropdown |
| `statusCode` / `error` / `filename` / `contentType` | Utdata |
### 4.3 Operationskatalog
| Nod.operation | När |
|---------------|-----|
| bridge.ncFileToPdf/Png/Html | Standardkonvertering NC-fil → NC-fil |
| bridge.htmlToOffice | Agentgenererad HTML/MD → office |
| bridge.fillTemplateSave | Fyll content controls/fält och spara kopia |
| bridge.compareVersionsPdf | Ny + gammal fil → PDF med ändringar |
| bridge.extractToPayload | Struktur-JSON till nästa nod |
| bridge.createAssetLink | Engångs-URL för insert i öppet dokument |
| nc-office.templates:list\|create | Office-mallar i richdocuments |
| nc-office.template:extractFields\|fillFields | Föredra när fileId finns |
| nc-office.document:direct\|public | Engångs redigerings-URL |
| nc-office.files:convert | Konvertera via Nextcloud (CODE bakom) |
| convert + extract + transform | Låg nivå när bridge inte räcker |
| wopi.discovery\|capabilities | Hälsokoll och mime→urlsrc |
| wopi.buildEditor | Bygg editorUrl om token redan finns |
| wopi.checkFileInfo\|getFile | Endast felsökning av WOPI-host |
---
## 5. Recept
### A. NC-fil till PDF
```
inject {ncPath} → collabora-bridge ncFileToPdf → ev. filesharing createShare (OCS :1880)
```
Kontrollera `destNcPath` i svaret.
### B. Avtalsmall
```
extractFields eller extract contentcontrol
→ mappa data till fields/transform
→ fillTemplateSave eller template:fillFields med destination
→ valfritt ncFileToPdf
→ document:direct för mänsklig granskning
```
### C. Versionsdiff
```
{ncPath: ny, compareNcPath: gammal} → compareVersionsPdf
→ skicka PDF via Talk eller Mail-noden i OCS-paketet (:1880)
```
### D. Generera dokument
HTML i `payload` → `htmlToOffice` format docx eller pdf. Använd mall via convert `templateNcPath` om typografi måste följa husmall.
---
## 6. Vad du inte ska bygga
- En Node-RED-nod som postMessage:ar in i Collabora-iframe (kräver webbsida utanför iframen).
- Dynamisk Python mot share/Scripts/python (kräver paket på CODE och omstart).
- Andra CODE-container i compose (`code` körs redan med aliasgroup1).
- Portkrock på 1880 mot nextcloud-node-red.
---
## 7. Felsökning
| Symptom | Orsak | Åtgärd |
|---------|-------|--------|
| ECONNREFUSED :9980 | Fel Docker-nät | host.docker.internal, 172.17.0.2 eller network_mode host |
| Tomt convert-svar | CODE storage / fel URL | Anropa intern 9980, inte publik host |
| WebDAV 401 | App-lösen / user | Nytt app-lösen, samma uid som sökvägen |
| WebDAV 404 | Fel sökväg | Leading slash, rätt folder, URL-encode segment |
| extract tomt | Filter / capability | capabilities, prova documentproperties |
| WOPI 401/proof | Sessionstoken | Lämna WOPI. Använd WebDAV. |
| TLS-fel mot NC | Cert i containern | verifyTls=false |
---
## 8. Acceptanskriterier för ett flöde
- `capabilities` mot CODE returnerar JSON.
- En känd testdokumentsökväg konverteras till PDF under `/Dokument/OfficeOut/`.
- Originalfilen är oförändrad.
- Fel hamnar i `msg.error` och nodstatus röd, flödet kraschar inte tyst.
- Inga hemligheter i debug-payload till Talk.
---
## 9. Installation (Ubuntu)
```bash
# /home/ncadmin/nextcloud-collabora-nodered
chmod +x install.sh
./install.sh
# UI: http://192.168.1.26:1881
```
Överföring från Windows:
```bash
./package.sh # skapar artifacts/nextcloud-collabora-nodered-1.0.0.tar.gz
scp artifacts/*.tar.gz ncadmin@192.168.1.26:/home/ncadmin/
# på servern:
tar -xzf nextcloud-collabora-nodered-1.0.0.tar.gz -C nextcloud-collabora-nodered
cd nextcloud-collabora-nodered && ./install.sh
```
---
## 10. Arkitektur
```
Befintligt (orört):
nextcloud-ocs 16 noder + nextcloud-config
container nextcloud-node-red :1880
CODE "code" :127.0.0.1:9980
Ny yta (det här paketet):
nc-collab-config
nc-office richdocuments OCS
collabora-convert /cool/convert-to
collabora-extract /cool/extract-document-structure
collabora-transform /cool/transform-document-structure
collabora-wopi discovery, capabilities, editor-URL
collabora-bridge agent-pipelines
```
---
*cloud.hannesahlin.se · nextcloud-collabora-nodered v1.0*