Installing excalidraw-backend for Whiteboard feature on self-hosted Jitsi Mee

I managed to get everything up and running, but found the documentation lacking. Maybe this will be useful to the next person.

My installation:

  • Self-hosted Jitsi Meet on Debian bullseye, using the binary distribution from the jitsi folks
  • Nginx as webserver in front
  • Dedicated rented server just for Jitsi
  • Open instance, anyone can join, first person is moderator

What the whiteboard integration does:

  • Moderator has a new button “Show whiteboard”
  • That displays a whiteboard - similar to a screen share, Whiteboard becomes main window, participants are small videos in a strip
  • It is based on Excalidraw
  • After the whiteboard was shown once, anyone can hide / show it for themselves
  • Does not work on mobile
  • Whiteboard is collaborative - everyone can edit the shared diagram
  • Diagram is ephemeral - when the video call terminates, everything is lost
  • But anyone can export it to SVG / PNG first

The crucial thing is the collaboration feature:

  • Needs another server component excalidraw-backend
  • This backend is programmed in node.js - different to the Java-based jvb and jicofo components
  • Can be hosted on the same server or somewhere else
  • Even if the backend is not running, Jitsi might show the whiteboard - it’s just that everyone has their own whiteboard, not seeing anyone else’s. In this scenario, there are helpful errors in the browser’s Javascript console.

Step 1 Install Node.js
node.js uses its own package manager “npm”. Debian bullseye only has a version that is too old for excalidraw-backend.
I had success using the following as /etc/apt/sources.list.d/nodesource.list

deb [signed-by=/usr/share/keyrings/nodesource.gpg] https://deb.nodesource.com/node_16.x bullseye main

This is a binary distribution of debian packages made by Nodesource - I know nothing about them, but a cursory look at their website and internet search turned up no red flags to me, they seem to be well-regarded.
Then just the normal

apt update
apt install npm

Step 2 Install excalidraw-backend
There does not seem to be a debian package nor a binary distribution. So I created a user “excali” with a home directory of /opt/excalidraw-backend . Then:

su - excal
cd /opt
git clone https://github.com/jitsi/excalidraw-backend.git
npm install

Running as-is does not work, because it tries to bind to ports 80 and 9090 which are already used by nginx / jvb. So:

echo "PORT=3002" >.env.production

Edit src/index.ts - find the block

// listens on host:9090/metrics
prometheus.metrics(io, {
    port: 9091,
    collectDefaultMetrics: true
});

and change the 9090 to 9091 (or whatever). It seems like there should be a way to put this in the .env, but I cannot see how.

DEBUG=* npm start

should start the server in debugging mode, showing you connection attempts and so on. Without the DEBUG=*, it is really quiet, not even outputting “server ready” or similar.

Step 3 Configure other jitsi components
Do as How to enable new whiteboard feature? - #15 by saghul says. Prosody needs to have room_metadata - mine didn’t. The config.js for your site needs to have ‘whiteboard’ in the toolbarButtons and also a section similar to

 whiteboard: {
          enabled: true,
          collabServerBaseUrl: 'YOURDOMAIN.com'
     },

Step 4 Configure nginx to do SSL termination for the excalidraw-backend websocket
The excalidraw-backend is running now, but it is not SSL-terminated. Since my Jitsi of course is, browsers will not connect to excalidraw-backend without SSL, as I saw in the Javascript console. I saw the URL ends in socket.io, so I added the following to my nginx config:

    # excalidraw-backend websockets
    location = /socket.io/ {
        proxy_pass http://127.0.0.1:3002/socket.io/?$args;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $http_host;
        tcp_nodelay on;
    }

This forwards these websockets to the correct port.

Step 5 Automatic startup
Now, everything should work, albeit very slowly because the debugging is extensive. So Ctrl-C the backend and let’s put in a systemd service into /etc/systemd/system/excalidraw.service :

[Unit]
Description=Excalidraw-backend
Requires=network.target
After=network.target

[Service]
User=excali
WorkingDirectory=/opt/excalidraw-backend
Type=simple
ExecStart=/usr/bin/npm start
Restart=on-failure
RestartSec=250s
TimeoutStartSec=20s
TimeoutStopSec=1min

[Install]
WantedBy=multi-user.target

Then, “systemctl enable excalidraw.service” to have it startup at launch and “systemctl start excalidraw.service” to start it now.

That’s it. Seems to be running stable for me now. Thanks for the great feature, made our meetings better!

8 Likes

Thanks for sharing!

hello
I have a question about the jitsi whiteboard.
I have installed everything according to instructions and can activate the whiteboard via the menu in a session.

thank you for this tutorial!

how exactly is the whiteboard supposed to work?
i can write and draw but no one else but myself can see it!?

Hi, this means that the browser does not connect to the excalidraw-backend. If you started the backend in debugging mode, you will see connection attempts there. The other place to look is the JavaScript console of your browser, there will be error messages there if the websocket connection does not work.

thanks a lot, I will check this

Is it also possible to host the excalidraw-backend as an docker container?