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] 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
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: ''

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, so I added the following to my nginx config:

    # excalidraw-backend websockets
    location = / {
        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 :


ExecStart=/usr/bin/npm start


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!


Thanks for sharing!

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?

Hi, thank you for this steps. I have same problem as atiw.
On browser level I’m getting error
WebSocket connection to ‘wss://mydomain/’ failed:
When I disabled excalidraw.service and run manually DEBUG, I’m not getting any logs.

I even add port 3002 in firewall exception, but still nothing.

Have you some hints?

Thanks in advance


@Emir_Avdispahic: I got this error, if there is no network connection possible to the backend… it means the backend is not reachable.

I did it with docker on the local machine - here are the additional steps to the guide above.
Step 1 Node.js is not necessary to install local, because it’s already in the docker container.

######### edit "Dockerfile" and edit/insert before "npm start"


CMD ["npm", "start"]

###### build it
docker build .

###### tag it
docker tag 2ee10f2e0641 excalidraw-backend

##### start it
docker run -p 3002:80 -d --restart unless-stopped excalidraw-backend

docker logs [containerid]

My problem is now:
If I open a whiteboard as a moderator, I can see connections and a lots of output in the docker logs of the backend.
But if another user connects, he can’t see the whiteboard.

If I compare it to in the browser network console: in my installation the websocket to the excalidraw backend is never opened for the non moderator users/clients.

Any ideas?

As others said it’s a nice attempt but it’s not working. If the op wants I can make a youtube video proving it, but then again, I’m no linux expert. It’s just annoying that it’s been months since this whiteboard has been added and like only 3 people managed to get it working and yet there’s no real full guide that works.

nano /etc/nginx/nginx.conf

excalidraw-backend websockets

location = / {
    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;

and then my web server is down on port 443. Can’t connect to it.

curl -k

curl: (7) Failed to connect to port 443: Connection refused

I’ve never been so lost and frustrated with computers until Jitsi Meet with Debian in Virtualbox, totally self-hosted. Worked up until I wanted the whiteboard now it’s nothing but explosions.

Like, work. Work you piece of excrement. Why can’t you just work like a normal machine?

1 Like

You are right, there is no installation documentation except this post here.

On my end the connections to the docker container and the debug logs in the container are working, from the localhost and from remote … if a user opens a whiteboard and then closes the connection.

# on the host
Excalidraw backend is up :)

# docker logs on the host ... the connections are coming from outside
docker logs xxxxxxxxx
2022-12-18T21:06:53.179Z encoding packet {"type":5,"data":["cli
2022-12-18T21:06:53.180Z encoded {"type":5,"data":["client-broa
ttachments":2} as 52-["client-broadcast",{"_placeholder":true,"num":0},{"_placeh
2022-12-18T21:06:54.197Z engine:ws received "41"
2022-12-18T21:06:54.197Z engine:socket packet
2022-12-18T21:06:54.197Z decoded 1 as {"type":1,"nsp":"/"}
2022-12-18T21:06:54.197Z got packet {"type":1,"nsp":"/"}
2022-12-18T21:06:54.198Z got disconnect packet
2022-12-18T21:06:54.198Z closing socket - reason client namespace disconnect
2022-12-18T21:06:54.221Z client close with reason transport close

The result is the same with docker container or standalone: the websocket for the “whiteboard initiator” is opened - and the communication is working BUT for the whiteboard “client” it never gets opened:


Sry for delayed reply, whiteboard is working. In my case , problem caused on scheduler lvl, where user doesn’t have rights to path where source files are. One question, how can I access frontend code since I want to change language?

You should be editing your site-specific config-file (/etc/nginx/sites-enabled/your.domain.tld.conf) instead of the nginx.conf.

Yup I figured it out and made a video installing from scratch to working whiteboard to possibly help others.


Haven’t watched it thoroughly but few things I spotted, you don’t need two DNS to make it work. One is enough, second is to use turns over 443 which is to cover some corporate networks where only 443 is allowed. And for the ports, you only need to expose publicly UDP 10000 and 3478 and TCP 443 and 5349. And if you are using the second DNS to use turns over 443 then you can skip the TCP 5349.

1 Like

That might be true if you install Jitsi Meet normally, but I’m using @emrah 's installer here: installers/jitsi-jibri at main · jitsi-contrib/installers · GitHub

which clearly says

Jitsi address and TURN address must be different and don’t use an IP as the host address

And it won’t work if you don’t put it two different DNS. His installer seems the easiest for those unfamiliar with all this stuff and so I followed the instructions.

How can I install and integrate whiteboard with docker-jitsi-meet. I followed above mentioned steps but it is not reflecting on my machine since these steps are applied for self-hosted jitsi-meet. As my setup is using docker-jitsi-meet so I need your help to guide for how to install whiteboard on docker-jitisi-meet.

Hi everyone!

I made everything from the tutorial, and jitsi-meet still don’t show the whiteboard button on the toolbar.
The excalidraw.service is working fine, and I added config settings also.
Can you tell me, how can I debug jitsi-meet ? So I didn’t have error message on consele and logs.
I looked for a function in the code, and find out _whiteboardEnabled is the function. Can I see step-by-step where is the connectenion between jitsi-meet and excalidraw?


We’ve gotten the same problem here.
With the latest Jitsi Meet, nginx, npm, webpack version installed, also strictly followed the tutorial step-by-step.

In dev mode everything works just fine as it should, but soon as we switch into production mode the “Show whiteboard” button disappears.

We are fighting with this issue since days and we just don’t understand why it doesn’t work because all the toolbar modules, whiteboard + nginx configs enabled and setted just like in the documentation.

Would be great and very appreciated if you guys could give us some advice.

Thanks in advance!