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 — drawing sessions stay on your infrastructure. No design file transits a third party.
• 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 build the image substituting your domain. Replace collab.yourdomain.com with the subdomain you allocate to excalidraw-room:

   git clone https://github.com/excalidraw/excalidraw.git
   cd excalidraw
   docker build \
     --build-arg VITE_APP_WS_SERVER_URL=wss://collab.yourdomain.com \
     -t my-excalidraw:latest .

   This step bakes the WebSocket server URL into the JavaScript bundle. If you change domains later, you will need to rebuild. The official excalidraw/excalidraw image works for local testing but points to Excalidraw's public server — unusable for a sovereign deployment.

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
       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.

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