search

nextcloud / whiteboard

Create & collaborate on an infinite canvas!
https://apps.nextcloud.com/apps/whiteboard
GNU Affero General Public License v3.0
59 stars 8 forks source link
nextcloud nextcloud-app whiteboard

readme

Nextcloud Whiteboard

REUSE status

The official whiteboard app for Nextcloud. It allows users to create and share whiteboards with other users and collaborate in real-time.

You can create whiteboards in the files app and share and collaborate on them.

Features

Backend

Standalone websocket server for Nextcloud Whiteboard

Running the whiteboard server is required for the whiteboard to work. The server will handle real-time collaboration events and broadcast them to all connected clients, which means that the server must be accessible from the users browser, so exposing it for example throuhg a reverse proxy is necessary. It is intended to be used as a standalone service that can be run in a container.

We require the following connectivity:

On the Nextcloud side, the server must be configured through:

occ config:app:set whiteboard collabBackendUrl --value="http://nextcloud.local:3002"
occ config:app:set whiteboard jwt_secret_key --value="some-random"

Running the server

Local node

This mode requires at least Node 20 and NPM 10 to be installed. You can clone this repository, checkout the release version matching your whiteboard app. The server can be run locally using the following command:

npm ci
JWT_SECRET_KEY="some-random" NEXTCLOUD_URL=http://nextcloud.local npm run server:start

Docker

The server requires the NEXTCLOUD_URL environment variable to be set to the URL of the Nextcloud instance that the Whiteboard app is installed on. The server will connect to the Nextcloud instance and listen for whiteboard events.

The server can be run in a container using the following command:

docker run -e JWT_SECRET_KEY=some-random -e NEXTCLOUD_URL=https://nextcloud.local --rm ghcr.io/nextcloud-releases/whiteboard:release

Docker compose can also be used to run the server:

version: '3.7'
services:
  nextcloud-whiteboard-server:
    image: ghcr.io/nextcloud-releases/whiteboard:release
    ports:
      - 3002:3002
    environment:
      - NEXTCLOUD_URL=https://nextcloud.local
      - JWT_SECRET_KEY=some-random-key

Building the image locally

While we publish image on the GitHub container registry you can build the image locally using the following command:

docker build -t nextcloud-whiteboard-server -f Dockerfile .

Reverse proxy

Apache

ProxyPass /whiteboard http://localhost:3002/
RewriteEngine on
RewriteCond %{HTTP:Upgrade} websocket [NC]
RewriteCond %{HTTP:Connection} upgrade [NC]
RewriteRule ^/?whiteboard/(.*) "ws://localhost:3002/$1" [P,L]

Nginx

location /whiteboard/ {
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $host;

    proxy_pass http://localhost:3002/;

    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Caddy v2

handle_path /whiteboard/* {
    reverse_proxy http://127.0.0.1:3002
}

Storage Strategies and Scaling

The whiteboard application supports two storage strategies: LRU (Least Recently Used) cache and Redis. Each strategy has its own characteristics and is suitable for different deployment scenarios.

Storage Strategies

1. LRU (Least Recently Used) Cache

The LRU cache strategy is an in-memory storage solution that keeps the most recently used items in memory while automatically removing the least recently used items when the cache reaches its capacity.

Advantages:

Limitations:

Configuration: To use the LRU cache strategy, set the following in your .env file:

STORAGE_STRATEGY=lru

Resources:

2. Redis

Redis is an in-memory data structure store that can be used as a database, cache, and message broker. It provides persistence and supports distributed setups.

Advantages:

Limitations:

Configuration: To use the Redis strategy, set the following in your .env file:

STORAGE_STRATEGY=redis
REDIS_URL=redis://[username:password@]host[:port][/database_number]

Replace the REDIS_URL with your actual Redis server details.

Scaling and Deployment

Single-Node Deployment

For small to medium-sized deployments, a single-node setup can be sufficient:

  1. Choose either LRU or Redis strategy based on your persistence needs.
  2. Configure the .env file with the appropriate STORAGE_STRATEGY.
  3. If using Redis, ensure the Redis server is accessible and configure the REDIS_URL.
  4. Start the whiteboard server.

Multi-Node Deployment (Clustered Setup)

For larger deployments requiring high availability and scalability, a multi-node setup is recommended:

  1. Use the Redis storage strategy.
  2. Set up a Redis cluster or a managed Redis service.
  3. Configure each node's .env file with: 
    STORAGE_STRATEGY=redis
REDIS_URL=redis://[username:password@]host[:port][/database_number]
  4. Set up a load balancer to distribute traffic across the nodes.
  5. Ensure all nodes can access the same Redis instance or cluster.

Scaling WebSocket Connections

The whiteboard application uses the Redis Streams adapter for scaling WebSocket connections across multiple nodes. This adapter leverages Redis Streams, not the Redis Pub/Sub mechanism, for improved performance and scalability.

When using the Redis strategy, the application automatically sets up the Redis Streams adapter for WebSocket scaling. This allows multiple server instances to share WebSocket connections and real-time updates.

Resources:

Considerations for Multi-Node Setups

Choosing the Right Strategy

By carefully considering your deployment needs and choosing the appropriate storage strategy, you can ensure optimal performance and scalability for your whiteboard application.

Known issues

If the integration_whiteboard app was previously installed there might be a leftover non-standard mimetype configured. In this case opening the whiteboard may fail and a file is downloaded instead. Make sure to remove any entry in config/mimetypealiases.json mentioning whiteboard and run occ maintenance:mimetype:update-db and occ maintenance:mimetype:update-js.