Self-Hosting Excalidraw on a VPS: Open Source Whiteboard

Why self-host Excalidraw instead of using the public version

Concrete benefits

• Zero software subscription — both components (interface and collaboration server) are MIT. You pay for the VPS, nothing else.
• Mockup confidentiality — live drawing stays on your infrastructure. The saved scene and a room's images still need handling (Firebase by default): see “What really works when self-hosting”.
• Access under your control — IP allowlist, OIDC SSO or HTTP Basic Auth in front of nginx depending on the required isolation level.
• Sessions and members scale with VPS RAM — no per-plan cap; the only limit is server RAM, and excalidraw-room is a lightweight Node.js service.
• Optional persistence — mount a Docker volume or connect an S3-compatible bucket to archive boards exported as JSON.
• Integration into a self-hosted stack — an Excalidraw instance alongside Penpot, Mattermost or Docmost closes the SaaS perimeter for an entire agency.

Architecture: two containers, distinct roles

Prerequisites

Prerequisites checklist

• A VPS with at least 1 vCPU and 512 MB RAM (1 GB recommended for a team).
• Docker Engine and Docker Compose Plugin installed (docker compose version to verify).
• A domain name pointed at the VPS IP — without TLS, WebSockets are blocked by modern browsers.
• Root SSH access or a user with sudo rights.
• A valid TLS certificate — ServOrbit configures Let's Encrypt automatically.

Deploy Excalidraw in 5 steps

1. 01

   Create the VPS and install Docker

   Provision an Ubuntu 24.04 VPS from your ServOrbit dashboard. Once connected over SSH, if Docker is not yet installed, run:

   curl -fsSL https://get.docker.com | sh

   Verify Docker Compose Plugin responds before continuing:

   docker compose version

2. 02

   Build the image with your collaboration URL

   Clone the official repository, then set the room address in the repository's .env.production file before building. Replace collab.yourdomain.com with the subdomain you allocate to excalidraw-room:

   git clone https://github.com/excalidraw/excalidraw.git
cd excalidraw
sed -i 's|^VITE_APP_WS_SERVER_URL=.*|VITE_APP_WS_SERVER_URL=https://collab.yourdomain.com|' .env.production
docker build -t my-excalidraw:latest .

   Why not --build-arg? The upstream Dockerfile declares no ARG for the VITE_APP_* variables: a --build-arg VITE_APP_WS_SERVER_URL=… never reaches the build command, the image builds normally and keeps pointing at Excalidraw's server. The upstream .dockerignore also admits only .env.development and .env.production, so a .env.production.local would be ignored. The address is baked into the bundle, so changing domain means rebuilding.

   Check the result: docker run --rm --entrypoint sh my-excalidraw:latest -c "grep -rl oss-collab.excalidraw.com /usr/share/nginx/html || echo clean" must print clean. The official excalidraw/excalidraw image is fine for local trials, but it targets Excalidraw's public services.

3. 03

   Write the docker-compose.yml file

   Create a working directory and write the following file. Both services listen internally; nginx (next step) is the only public entry point:

   mkdir ~/excalidraw-stack && cd ~/excalidraw-stack

   docker-compose.yml contents:

   services:
     excalidraw:
       image: my-excalidraw:latest
       restart: unless-stopped
       networks:
         - excalidraw
   
     excalidraw-room:
       image: excalidraw/excalidraw-room:latest
       environment:
         - CORS_ORIGIN=https://draw.yourdomain.com
       restart: unless-stopped
       networks:
         - excalidraw
   
   networks:
     excalidraw:

   Start the stack:

   docker compose up -d

4. 04

   Configure nginx with WebSocket headers

   This is the step where most deployments silently fail: without the Upgrade and Connection headers, the browser opens a plain HTTP connection instead of a WebSocket, and collaboration appears not to work with no visible error message.

   nginx block for the Excalidraw frontend (draw.yourdomain.com):

   server {
       listen 443 ssl;
       server_name draw.yourdomain.com;
   
       location / {
           proxy_pass http://excalidraw:80;
           proxy_set_header Host $host;
       }
   }

   nginx block for the room server (collab.yourdomain.com):

   server {
       listen 443 ssl;
       server_name collab.yourdomain.com;
   
       location / {
           proxy_pass http://excalidraw-room:80;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection "upgrade";
           proxy_set_header Host $host;
           proxy_read_timeout 86400s;
       }
   }

   Reload nginx (nginx -s reload) after placing the blocks.

5. 05

   Test real-time collaboration

   Open https://draw.yourdomain.com in two tabs or two different browsers. In the toolbar, click Live collaboration and create a session. Copy the session link into the second tab.

   Draw something in the first tab: the stroke should appear in the second in real time. If it does not, check the WebSocket headers in nginx first (browser network devtools show whether the connection upgraded to 101 Switching Protocols). A 200 status on the WebSocket request means nginx did not pass the Upgrade headers.

   Then open the browser's network tab: the real-time connection must target collab.yourdomain.com, never oss-collab.excalidraw.com. What Firebase receives is covered in the next section.

What really works when self-hosting

Three possible setups, and what each leaves with a third party

• Setup A — room only (the one in this guide). You change VITE_APP_WS_SERVER_URL and nothing else. Live drawing goes through your server; the saved scene and the rooms' images are still written to Excalidraw's Firebase. Acceptable for low-sensitivity boards, not to be presented as “nothing with a third party”.
• Setup B — room + your own Firebase project. You create a Firebase project of your own and put its JSON configuration in VITE_APP_FIREBASE_CONFIG. The code reads only that variable; we have not deployed this end to end, and Firebase remains a Google service, not self-hosting in the strict sense.
• Setup C — solo instance. You serve the interface alone, with no room and no link: everyone draws, exports to .excalidraw or an image, and archives the files with you. Nothing goes to a third party for collaboration, since there is none.
• What does not exist on the official side. No open storage server for #json= links, and no option that moves the whole perimeter to your domain through a single runtime variable. If your requirement is “no data with a third party” with collaboration and sharing, the honest answer is adaptation or fork work, not an installation.

Variable → function → what breaks without it

Scroll the table

Checking who receives what

Troubleshooting: collaboration will not start, or remembers nothing

Symptoms, causes, remedies

• The session goes to oss-collab.excalidraw.com (network tab) although you built your own image. Cause: the address was not picked up at build time (--build-arg has no effect, .env.production.local is ignored by the .dockerignore). Remedy: edit .env.production, rebuild, replay the grep check from step 2. A domain change follows the same rule.
• The browser's connection to the room is refused. Frequent cause after setting CORS_ORIGIN: the origin does not exactly match the page's (http scheme instead of https, port, trailing slash). Remedy: the value must be the interface's exact origin, for example https://draw.yourdomain.com.
• Strokes appear live, but a participant who joins later, or after a room restart, does not find the content or the images. Cause: the scene and images are saved through Firebase, not by excalidraw-room, which retains nothing. If VITE_APP_FIREBASE_CONFIG is empty or unreachable, nothing is read back. Remedy: choose setup A or B above.
• Warning Error JSON parsing firebase config. Supplied value: in the browser console. Cause: VITE_APP_FIREBASE_CONFIG is not valid JSON, most often because of badly protected quotes or a line break in the file. Remedy: JSON on a single line, in single quotes in .env.production, as in the upstream file.
• Link sharing fails, or the link produced points to json.excalidraw.com. Cause: VITE_APP_BACKEND_V2_POST_URL and VITE_APP_BACKEND_V2_GET_URL were not changed, or point to a server that does not implement the expected API. Remedy: keep the default knowingly, or exchange .excalidraw files.
• Encryption or key-generation error on a local network over http://. Cause: the browser's encryption API (window.crypto) is only exposed in a secure context; the upstream thread flags this trap for local-network self-hosting. Remedy: serve the interface over HTTPS (or on localhost), as the TLS prerequisite above requires.

Self-hosted Excalidraw vs SaaS alternatives

Scroll the table

Going further: SSO and IP allowlists

allow 203.0.113.0/24;
allow 198.51.100.42;
deny all;

Integration in a self-hosted stack