hocuspocus — das WebSocket-Backend der Collab-Suite.

Architektur und Environment

hocuspocus ist ein Standalone-Node-Service auf Basis von @hocuspocus/server und yjs. Default-Port 1234, Stack Node-20-Alpine plus TypeScript. Multi-Instance-Sync läuft über Redis/Valkey Pub-Sub; ohne REDIS_URL läuft der Service im Single-Instance-Modus mit In-Process-Memory.

Browser (CKEditor 5 + Yjs Client, via moselwal/collab-rte)
   ↓ ws://host:1234/?docId=...&token=<JWT>
moselwal/hocuspocus (dieser Service)
   ├─ @hocuspocus/extension-redis  (Multi-Instance State-Sync via Redis Pub/Sub)
   ├─ @hocuspocus/extension-logger
   └─ HTTP (REST) → TYPO3-Backend (moselwal/collab-core)
         ├─ onAuthenticate   → POST /api/collab/auth
         ├─ onLoadDocument   → POST /api/collab/document/load
         └─ onStoreDocument  → POST /api/collab/document/store

Environment-Variablen

Container-Konvention

Rootless (UID/GID 1001 hocuspocus), non-privileged Port-Bind. Image-Name intern registry.moselwal.io/development/moselwal/hocuspocus. Für Production gehört Caddy oder ein anderer TLS-terminierender Reverse-Proxy davor — der WebSocket-Listener spricht aktuell kein TLS direkt.

Empfohlene compose-Definition (Auszug)

services:
  hocuspocus:
    image: registry.moselwal.io/development/moselwal/hocuspocus:latest
    environment:
      TYPO3_AUTH_URL:  httpd/api/collab/auth
      TYPO3_LOAD_URL:  httpd/api/collab/document/load
      TYPO3_STORE_URL: httpd/api/collab/document/store
      REDIS_URL: redis://${KEYVALUE_HOST:-keyvaluecache}:6379
    networks: [internal]
    healthcheck:
      test: ["CMD", "node", "-e", "require('net').connect(1234).on('connect',()=>process.exit(0)).on('error',()=>process.exit(1))"]
      interval: 30s
      timeout: 5s
      retries: 3

Status-Hinweis

Stand v0.1.0 sind die API-Pfade und Body-Formate noch nicht vollständig mit collab-core synchronisiert (im AUDIT als HIGH-1/HIGH-2 vermerkt) — Multi-User-Edit läuft Stand jetzt noch nicht. Die Architektur und das Image-Layout sind stabil, der Sync-Bug ist auf der Roadmap.