> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdoc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-Hosted Collaboration

Run your own collaboration infrastructure for full control over data, persistence, and scaling.

## Why self-host?

> [card] Data Control
>
> Keep all data on your infrastructure

> [card] Custom Persistence
>
> Use your own database (PostgreSQL, S3, Redis)

> [card] On-Premise
>
> Deploy behind your firewall

> [card] No Vendor Lock-in
>
> Standard Yjs protocol, portable data

## Architecture

```mermaid theme={null}
flowchart TB
    subgraph infra[Your Infrastructure]
        A[User A<br/>SuperDoc] <--> WS[WebSocket Server<br/>Yjs Provider]
        WS <--> B[User B<br/>SuperDoc]
        WS --> DB[(Persistence<br/>DB, S3, etc.)]
    end
```

## Choose your approach

SuperDoc's integration contract is provider-agnostic: pass `{ ydoc, provider }` to `modules.collaboration` and the server choice is yours. Any Yjs-compatible server works.

| Option | Notes | Setup Time |
| - | - | - |
| [YHub](https://docs.superdoc.dev/guides/collaboration/yhub.md) | Advanced Yjs backend for attribution, activity, and revision-history workflows. Beta; validate licensing and infrastructure requirements. | 1+ hour |
| [Hocuspocus](https://docs.superdoc.dev/guides/collaboration/hocuspocus.md) | Mature self-hosted Yjs server with auth, persistence, and scaling hooks. | 30 mins |
| [SuperDoc Yjs](https://docs.superdoc.dev/guides/collaboration/superdoc-yjs.md) | Minimal reference server for prototypes and local development. Not production infrastructure. | 30 mins |

## At a glance

> [tab] YHub
>
> Advanced Yjs backend for attribution, activity, and revision-history workflows. Redis + Postgres backing. Beta; validate licensing and infrastructure requirements.
>
> [Setup guide](https://docs.superdoc.dev/guides/collaboration/yhub.md)

> [tab] Hocuspocus
>
> Mature self-hosted Yjs server with auth, persistence, and scaling hooks.
>
> ```bash theme={null}
> npm install @hocuspocus/server @hocuspocus/provider
> ```
>
> [Setup guide](https://docs.superdoc.dev/guides/collaboration/hocuspocus.md)

> [tab] SuperDoc Yjs
>
> A small Yjs WebSocket server we ship for prototypes and local development. Not production infrastructure: no built-in auth, persistence, scaling, or observability.
>
> ```bash theme={null}
> npm install @superdoc-dev/superdoc-yjs-collaboration
> ```
>
> [Reference](https://docs.superdoc.dev/guides/collaboration/superdoc-yjs.md)

## Client connection options

The supported contract is provider-agnostic: you create the Yjs provider, SuperDoc plugs into it.

### Provider-agnostic (recommended)

```javascript theme={null}
import { HocuspocusProvider } from '@hocuspocus/provider';
import * as Y from 'yjs';

const ydoc = new Y.Doc();
const provider = new HocuspocusProvider({
  url: 'wss://your-server.com',
  name: 'document-123',
  document: ydoc
});

new SuperDoc({
  selector: '#editor',
  modules: {
    collaboration: { ydoc, provider }
  }
});
```

This shape works with any Yjs provider: `HocuspocusProvider`, `WebsocketProvider` from `y-websocket` (compatible with YHub and SuperDoc Yjs), `LiveblocksYjsProvider`, or your own.

### URL-based (deprecated)

> [!WARNING]
>
> This path is deprecated. SuperDoc creates the provider internally and emits a console warning. Use the provider-agnostic shape above for new code.

```javascript theme={null}
new SuperDoc({
  selector: '#editor',
  modules: {
    collaboration: {
      url: 'wss://your-server.com/doc',
      token: 'auth-token'
    }
  }
});
```

## Requirements

### Server

* Node.js 18+
* WebSocket support (native or via library)
* Persistent storage for Yjs updates or snapshots
* Optional object storage for DOCX exports and archive snapshots

### Network

* WSS (WebSocket Secure) in production
* Proper CORS configuration
* Load balancer with sticky sessions (if scaling)

## Next steps

> [card] [YHub setup](https://docs.superdoc.dev/guides/collaboration/yhub.md)
>
> Attribution and revision-history workflows (beta)

> [card] [Hocuspocus setup](https://docs.superdoc.dev/guides/collaboration/hocuspocus.md)
>
> Mature self-hosted Yjs server

> [card] [SuperDoc Yjs reference](https://docs.superdoc.dev/guides/collaboration/superdoc-yjs.md)
>
> Minimal server for prototypes and local development

> [card] [Configuration](https://docs.superdoc.dev/editor/collaboration/configuration.md)
>
> All client-side options and events


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.