Nextcloud Whiteboard Setup Guide: Install, Configure & Deploy

Nextcloud Whiteboard is a self-hosted visual collaboration tool built on Excalidraw, allowing teams to draw, sketch, and brainstorm in real-time without sending data to third-party services. To use it, you need the Whiteboard app AND a separate WebSocket backend server for real-time sync; this two-part architecture is non-negotiable and trips up most first-time setups.

This guide walks through the full installation process, from app deployment through reverse proxy configuration, plus troubleshooting steps for the setups that fail.

What is Nextcloud Whiteboard?

Nextcloud Whiteboard is a canvas-based collaboration tool that shipped with Nextcloud Hub 9 on October 8, 2024. It sits on top of Excalidraw, an open-source drawing library with 134,800 GitHub stars used by Google Cloud, Meta, CodeSandbox, Notion, and Obsidian. The Nextcloud integration adds permissions, sharing controls, and real-time collaboration baked into your Nextcloud instance.

Users create whiteboards, invite team members, and draw shapes, arrows, text, and images. Changes sync in real-time across all connected clients. You can export as PNG, SVG, or JSON. It integrates with Nextcloud Talk, so you can brainstorm while on a video call.

The Nextcloud Whiteboard repository has 231 GitHub stars and active maintenance. If you're already running Nextcloud for file storage and team collaboration, Whiteboard extends that without adding another SaaS tool.

Why You Need a WebSocket Backend Server

This is the critical piece most guides skip. The Whiteboard app alone cannot handle real-time sync. Multiple users editing the same whiteboard need a dedicated backend that listens on a WebSocket connection, broadcasts changes, and manages conflict resolution.

The app sends drawing events (stroke, shape, delete) to the backend. The backend relays those events to every other connected client in milliseconds. Without it, edits do not sync in real-time; you get a dead, single-user tool.

You have two options: run the Node.js backend yourself (Docker recommended), or subscribe to a managed backend service like TAB.DIGITAL's hosted version. For a self-hosted setup, Docker is easier than raw Node.js.

Performance scales roughly as: 50 concurrent users need 2 vCPU + 1 GB RAM; 100 users need 4 vCPU + 2 GB RAM, according to Nextcloud's GitHub benchmarking. If you exceed that, add more replicas behind a load balancer.

Step 1: Install the Whiteboard App

The app installation is straightforward. Log in to your Nextcloud instance as an admin.

1. Click your user avatar, top-right, and select "Apps".
2. Search for "Whiteboard".
3. Click the Whiteboard result and select "Download and enable".
4. Nextcloud downloads the app and activates it. You'll see a new "Whiteboard" icon in the top menu.

Alternatively, use the command line:

npm install -g @nextcloud/app-installer
nextcloud-app install whiteboard

Or via occ if you're inside the container:

sudo -u www-data php occ app:install whiteboard
sudo -u www-data php occ app:enable whiteboard

Verify it's active: Settings > Administration > Apps > Enabled Apps. "Whiteboard" should appear in the list.

At this point, the app is installed but non-functional. Clicking "Create new whiteboard" will fail silently or time out because the backend is missing.

Step 2: Deploy the WebSocket Backend

The backend is a Node.js service. Running it in Docker is simplest; it isolates dependencies and scales predictably.

Docker Deployment (Recommended)

Pull the official image:

docker pull ghcr.io/nextcloud/whiteboard-server:latest

Create a .env file with these settings:

JWT_SECRET=your-random-secret-key-here
PORT=8080
LOG_LEVEL=info
MAX_CONNECTIONS=500

Generate a strong JWT secret:

openssl rand -base64 32

Run the Docker container. Bind it to port 8080 on the local interface only (not exposed to the internet), then set up your reverse proxy to forward traffic to it:

docker run -d --name whiteboard-backend --env-file.env -p 127.0.0.1:8080:8080 ghcr.io/nextcloud/whiteboard-server:latest

Check the logs:

docker logs whiteboard-backend

You should see a "Server running" message in the output.

Node.js Deployment (Manual)

If you prefer to run without Docker:

git clone https://github.com/nextcloud/whiteboard whiteboard-server
cd whiteboard-server
npm install
export JWT_SECRET=$(openssl rand -base64 32)
export PORT=8080
npm start

Use a process manager like PM2 to keep it running:

npm install -g pm2
pm2 start server.js --name whiteboard
pm2 save
pm2 startup

Step 3: Configure the Reverse Proxy

Your Nextcloud sits behind Apache or Nginx. That proxy must forward WebSocket traffic to the backend running on port 8080.

WebSocket proxying is different from standard HTTP proxying. Headers like Connection: Upgrade, Upgrade: websocket, and Sec-WebSocket-Key must pass through unchanged, or the upgrade handshake fails.

Nginx Configuration

For Nginx, you need to:

1. Create an upstream block that points to your backend server (running on localhost port 8080)
2. Add a location block for /apps/whiteboard/socket that forwards to the upstream with WebSocket headers
3. Set appropriate timeout values (WebSocket connections are long-lived)
4. If using HTTPS (required), Nginx terminates SSL and forwards plain HTTP to the backend internally

The key headers are: proxy_set_header Upgrade $http_upgrade, proxy_set_header Connection "upgrade", proxy_set_header Host $host, and proxy timeouts of at least 86400 seconds.

Reload Nginx after making changes:

nginx -s reload

Apache Configuration

For Apache, you need to:

1. Enable mod_proxy_wstunnel and mod_rewrite modules
2. Add ProxyPass and ProxyPassReverse directives for the /apps/whiteboard/socket path, using the ws:// protocol scheme
3. Add rewrite rules to detect WebSocket upgrade requests and route them correctly
4. Restart Apache

Enable the modules:

sudo a2enmod proxy_wstunnel
sudo a2enmod rewrite
sudo systemctl restart apache2

Then add the proxy rules to your VirtualHost configuration. The mod_proxy_wstunnel module handles the WebSocket upgrade negotiation automatically.

Step 4: Link the Backend in Nextcloud Admin Settings

Now tell Nextcloud where the backend lives.

1. Log in as admin.
2. Click your avatar > Settings.
3. Select Administration > Whiteboard (on the left sidebar).
4. Enter the settings:
   • Collaboration Backend URL: Enter your Nextcloud's public HTTPS URL (the same domain your users access; Nextcloud will append the WebSocket path automatically).
   • JWT Secret: Paste the same secret you generated and set in the backend's environment.
5. Click "Save".

The JWT secret must match exactly on both sides. Nextcloud uses it to sign tokens; the backend verifies them. If they mismatch, authentication fails silently.

You can verify the connection by creating a test whiteboard. Open it, draw a shape, and wait 1-2 seconds. If it syncs, the backend is working. If nothing happens and you see console errors in the browser's DevTools, check:

1. The WebSocket endpoint is reachable: open your browser's Network tab and watch for a WebSocket connection to your domain's /apps/whiteboard/socket path. If it shows a 502 or 503, the reverse proxy is not forwarding correctly.
2. The JWT secret matches exactly (no extra spaces).
3. The backend is still running: docker logs whiteboard-backend.

Using Nextcloud Whiteboard: Features and Collaboration

Once the backend is live, the app unlocks full functionality.

Creating and Sharing Whiteboards

Click the Whiteboard icon in the Nextcloud menu (top bar). Click "Create new whiteboard". You get a blank canvas. Give it a name. Nextcloud saves it to a shared folder, usually Files/Whiteboards.

Share it like any Nextcloud file: right-click, "Share", and grant access to users or groups. Recipients get read-only or edit access depending on your permissions.

Drawing Tools

The toolbar on the left offers:

• Selection tool: Select, move, and delete shapes.
• Drawing tools: Freehand pen, lines, rectangles, circles, diamonds, arrows.
• Text: Add labels and annotations.
• Image insert: Paste or upload images from your computer.
• Eraser: Remove parts of drawings.
• Zoom and pan: Scroll to navigate; pinch to zoom on mobile.

Real-Time Collaboration

Invite another user into the same whiteboard. Open it together. Both users' cursors appear with their names. Edits sync instantly. If one user draws a box, the other sees it in 100-300ms (depending on network latency).

Color assignments help distinguish users. If 10 people edit the same whiteboard, each sees a different cursor color.

Integration with Nextcloud Talk

Start a Nextcloud Talk video call. During the call, click the "Whiteboard" button in the call interface. A shared whiteboard opens for all participants. Draw ideas while talking. When the call ends, the whiteboard persists in your Files folder.

This workflow beats switching between Zoom + Miro or Teams + Whiteboard because it's all in one instance and no data leaves your servers.

Exporting

Click the export button (arrow icon). Choose PNG (raster image), SVG (vector), or JSON (full editable format). PNG is useful for snapshots; JSON preserves all layers and is re-editable if you download and re-upload it.

Troubleshooting Common Setup Issues

Most problems fall into three buckets: WebSocket connection, JWT authentication, or reverse proxy configuration.

WebSocket Connection Fails (ERR_INVALID_URL in Console)

Symptom: Browser console shows WebSocket is closed before the connection is established.

Cause: The reverse proxy is not forwarding the WebSocket upgrade headers.

Fix:

• Nginx: Verify the proxy_set_header Upgrade and Connection directives are present and correct (see Step 3).
• Apache: Ensure mod_proxy_wstunnel is enabled with a2enmod proxy_wstunnel.
• Check the proxy logs for errors: look at /var/log/nginx/error.log (Nginx) or /var/log/apache2/error.log (Apache). Watch for 502, 503, or connection refused messages.

JWT Token Invalid (401 Unauthorized)

Symptom: WebSocket connects but no sync happens; backend logs show "Invalid token" or similar auth errors.

Cause: JWT secret in Nextcloud settings does not match the backend's JWT_SECRET environment variable.

Fix:

1. Retrieve the backend secret: docker exec whiteboard-backend echo $JWT_SECRET or check the .env file if running without Docker.
2. Go to Nextcloud > Settings > Administration > Whiteboard.
3. Paste the exact same secret. No extra spaces or hidden characters.
4. Click Save.
5. Refresh the whiteboard in your browser and try again.

Timeout When Opening a Whiteboard

Symptom: Whiteboard page loads but the canvas never appears; after 30 seconds, a timeout message displays.

Cause: Backend is not running or is not reachable on port 8080.

Fix:

1. Check the backend is running: docker ps | grep whiteboard-backend (Docker) or pm2 list (Node.js).
2. If not running, start it: docker start whiteboard-backend or pm2 start whiteboard.
3. Check logs for errors: docker logs whiteboard-backend | tail -20.
4. If the backend crashed (common error: "EADDRINUSE" port already in use), change the port in your .env file and update your reverse proxy configuration to match.

High Latency or Lag in Real-Time Sync

Symptom: Edits appear after 2-5 seconds instead of instantly.

Cause: Backend is under load or network latency between the reverse proxy and backend is high.

Fix:

• Scale the backend: Run multiple backend container replicas and use a load balancer (HAProxy or Nginx upstream) to distribute connections.
• Monitor resource usage: docker stats whiteboard-backend. If CPU or memory is consistently maxed, add more capacity.
• Check network latency: Run ping to your backend server from the Nextcloud instance. Latency greater than 50ms indicates a network problem.
• Enable gzip compression in your reverse proxy to reduce WebSocket payload size.

Frequently Asked Questions

What is Nextcloud Whiteboard?

Nextcloud Whiteboard is a self-hosted visual collaboration app based on Excalidraw. It allows teams to draw and brainstorm in real-time within your Nextcloud instance, keeping data private and under your control.

How do I install the Nextcloud Whiteboard app?

Log into Nextcloud as admin. Go to Apps, search for "Whiteboard", and click "Download and enable". The app installs in seconds. However, you must also deploy the WebSocket backend server for real-time collaboration to work.

Do I need a backend server for Nextcloud Whiteboard?

Yes. The app alone is non-functional. The backend is a separate Node.js service that handles real-time sync and conflict resolution. Without it, whiteboards are single-user only and changes do not sync.

How do I set up the WebSocket server for real-time collaboration?

Pull the official Docker image, set a JWT_SECRET in an .env file, and run the container on port 8080. Then configure your reverse proxy (Nginx or Apache) to forward WebSocket connections to that port. Finally, enter the JWT secret in Nextcloud's Whiteboard admin settings.

Can I use Nextcloud Whiteboard without a backend server?

No. The backend is mandatory for real-time collaboration. Skipping it leaves you with a non-functional app. You can run the backend yourself in Docker or subscribe to a managed backend service.

How do I configure reverse proxy (Apache/Nginx) for Whiteboard?

You must enable WebSocket upgrade headers. In Nginx, include proxy_set_header Upgrade $http_upgrade and proxy_set_header Connection "upgrade". In Apache, enable mod_proxy_wstunnel and use ProxyPass with the ws:// protocol. Both require forwarding requests to /apps/whiteboard/socket to the backend port. See Step 3 of this guide for details.

What are the performance requirements for Whiteboard?

According to Nextcloud benchmarks, 50 concurrent users need 2 vCPU and 1 GB RAM. 100 users need 4 vCPU and 2 GB RAM. Scale horizontally by running multiple backend containers behind a load balancer if you exceed 100 users.

Can I use Nextcloud Whiteboard with the mobile app?

Yes. Nextcloud's mobile app (iOS and Android) supports Whiteboard access. You can view and edit whiteboards on your phone. Drawing is easier on a tablet with a stylus, but the app works on any device with a Nextcloud client.

The Bottom Line

Nextcloud Whiteboard solves a real problem: team sketching and brainstorming without sending data to Miro or Microsoft. The setup is three steps--install the app, run the backend, configure the proxy--but the WebSocket piece is non-trivial if you have not done it before.

If you would rather skip the backend deployment and reverse proxy troubleshooting, Opsily's managed Nextcloud hosting handles all of it for you. The Whiteboard app and backend are pre-configured, so you open the app and start drawing immediately.