hocuspocus — the WebSocket backend of the Collab Suite.
hocuspocus integrates the Hocuspocus WebSocket server into the TYPO3 stack — as a backend for CRDT sync on top of Yjs, with persistence, authentication and multi-tenant support. Coming soon — content and API documentation will follow once the package is cleared for public release.
Architecture and environment
hocuspocus is a standalone Node service built on @hocuspocus/server and yjs. Default port 1234, stack Node-20-Alpine plus TypeScript. Multi-instance sync goes through Redis/Valkey pub/sub; without REDIS_URL the service runs in single-instance mode with in-process memory.
Browser (CKEditor 5 + Yjs client, via moselwal/collab-rte)
↓ ws://host:1234/?docId=...&token=<JWT>
moselwal/hocuspocus (this 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 variables
| Variable | Default | Description |
|---|---|---|
PORT | 1234 | TCP port for the WebSocket listener |
TYPO3_AUTH_URL | localhost/api/collab/auth | Endpoint for JWT validation |
TYPO3_LOAD_URL | localhost/api/collab/document/load | Document load endpoint |
TYPO3_STORE_URL | localhost/api/collab/document/store | Document store endpoint |
REDIS_URL | empty | Redis URL for multi-instance sync (e.g. redis://valkey:6379) |
Container conventions
Rootless (UID/GID 1001 hocuspocus), non-privileged port bind. Internal image name registry.moselwal.io/development/moselwal/hocuspocus. For production a TLS-terminating reverse proxy (Caddy or similar) belongs in front — the WebSocket listener does not speak TLS directly.
Recommended compose definition (excerpt)
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 note
At v0.1.0 the API paths and body formats are not yet fully aligned with collab-core (noted in the AUDIT as HIGH-1/HIGH-2) — multi-user edit does not yet work end-to-end. The architecture and the image layout are stable, the sync bug is on the roadmap.
Set up the Yjs backend early?
If you want to set up hocuspocus as a WebSocket backend for Yjs CRDT sync inside your TYPO3 stack or talk through the multi-tenant configuration with us, get in touch via the contact form.
Or email us directly: kontakt@moselwal.de