Running Excalidraw: Self-Hosted Collaborative Whiteboard

Excalidraw is one of those tools that looks deceptively simple — a hand-drawn style whiteboard in your browser — but once you start using it, you realize it’s replaced half your diagramming stack. Architecture diagrams, flowcharts, wireframes, quick sketches during meetings — it handles all of it with a clean, intuitive interface.

The hosted version at excalidraw.com works great, but self-hosting gives you full control over your data, private collaboration without third-party servers, and the ability to embed it into your own workflows.

What is Excalidraw?

Excalidraw is an open-source virtual whiteboard that produces hand-drawn style diagrams. It runs entirely in the browser, supports real-time collaboration, and exports to PNG, SVG, or its native .excalidraw format.

Why Self-Host Excalidraw?

• Privacy: Diagrams stay on your server — no data sent to third parties
• Collaboration: Real-time drawing with your team on your own infrastructure
• No accounts: Just open the URL and start drawing
• Offline capable: Works without internet once loaded
• Embeddable: Drop it into internal tools, wikis, or dashboards
• Library support: Share custom shape libraries across your team

Prerequisites

Before starting, you’ll need:

• A Linux server (Ubuntu 22.04+ or Debian 12+ recommended)
• Docker and Docker Compose installed
• A domain name pointed at your server (optional but recommended)
• A reverse proxy like Nginx Proxy Manager, Traefik, or Caddy
• At least 512MB RAM (Excalidraw is lightweight)

Step 1: Create the Project Directory

mkdir -p ~/excalidraw && cd ~/excalidraw

Step 2: Create the Docker Compose File

Create a docker-compose.yml file:

nano docker-compose.yml

Paste the following configuration:

version: "3.8"

services:
  excalidraw:
    image: excalidraw/excalidraw:latest
    container_name: excalidraw
    restart: unless-stopped
    ports:
      - "3030:80"
    environment:
      - REACT_APP_DISABLE_TRACKING=true
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:80"]
      interval: 30s
      timeout: 10s
      retries: 3

This gives you the core Excalidraw drawing interface. Port 3030 maps to the container’s port 80 — change it if you have a conflict.

Step 3: Enable Real-Time Collaboration (Optional)

Excalidraw’s collaboration feature requires a separate WebSocket server. If you want multi-user live drawing, add the collaboration backend:

version: "3.8"

services:
  excalidraw:
    image: excalidraw/excalidraw:latest
    container_name: excalidraw
    restart: unless-stopped
    ports:
      - "3030:80"
    environment:
      - REACT_APP_DISABLE_TRACKING=true
      - REACT_APP_WS_SERVER_URL=https://excalidraw-collab.yourdomain.com
    depends_on:
      - excalidraw-room

  excalidraw-room:
    image: excalidraw/excalidraw-room:latest
    container_name: excalidraw-room
    restart: unless-stopped
    ports:
      - "3031:80"

Replace excalidraw-collab.yourdomain.com with your actual domain pointing to the room server on port 3031.

Step 4: Start the Stack

docker compose up -d

Check that everything is running:

docker compose ps

You should see excalidraw (and excalidraw-room if you added collaboration) with status Up.

Step 5: Access Excalidraw

Open your browser and navigate to:

You’ll see the Excalidraw whiteboard immediately — no login, no setup wizard, just a blank canvas ready for drawing.

Step 6: Set Up a Reverse Proxy

For HTTPS and a clean URL, configure your reverse proxy. Here’s an example for Nginx Proxy Manager:

1. Add a new proxy host
2. Set the domain to excalidraw.yourdomain.com
3. Forward to your-server-ip:3030
4. Enable SSL with Let’s Encrypt
5. Turn on WebSocket support (important for collaboration)

If you’re using the collaboration server, create a second proxy host for excalidraw-collab.yourdomain.com pointing to port 3031, also with WebSocket support enabled.

Caddy Configuration

If you prefer Caddy, add to your Caddyfile:

Caddy handles HTTPS automatically.

Step 7: Custom Libraries

One of Excalidraw’s best features is custom shape libraries. You can create reusable components — server icons, cloud shapes, UI elements — and share them across your team.

To create a library:

1. Draw your shapes in Excalidraw
2. Select the elements you want to save
3. Click the library icon (book) in the toolbar
4. Choose “Add to library”

Libraries are stored in the browser’s local storage by default. To share them, export as .excalidrawlib files and distribute to your team.

Public Libraries

The Excalidraw community maintains a collection of public libraries at libraries.excalidraw.com. You can browse and install networking diagrams, AWS icons, UI components, and more directly into your self-hosted instance.

Troubleshooting

Blank Page After Loading

This usually means the static assets aren’t being served correctly. Check:

docker logs excalidraw

If you see 404 errors, ensure your reverse proxy isn’t stripping paths. Excalidraw needs all its static files served from the root path.

Collaboration Not Working

Real-time collaboration requires WebSocket connections. Common fixes:

• Enable WebSocket support in your reverse proxy
• Verify REACT_APP_WS_SERVER_URL points to the correct, accessible URL
• Check that the excalidraw-room container is running: docker logs excalidraw-room
• Ensure both services can communicate (same Docker network if needed)

High Memory Usage

Excalidraw is a static frontend app, so the server footprint is tiny. If you see high memory usage, it’s likely the browser tab — complex drawings with hundreds of elements can use significant client-side memory. This isn’t a server issue.

Updating Excalidraw

cd ~/excalidraw
docker compose pull
docker compose up -d

Excalidraw stores drawings in the browser (IndexedDB), so updates won’t lose any work. Just pull the latest images and restart.

Tips and Tricks

• Keyboard shortcuts: Press ? to see all shortcuts. L for line, R for rectangle, D for diamond — they speed things up dramatically
• Dark mode: Click the moon icon in the top right for dark theme
• Export options: Ctrl+Shift+E exports to PNG, Ctrl+Shift+S saves as SVG
• Embed in Notion/Confluence: Export as SVG and embed directly, or use the .excalidraw format with plugins
• Version control: Save .excalidraw files in Git — they’re JSON, so diffs work great

Security Considerations

Excalidraw is a client-side application — all drawing happens in the browser. The server only serves static files (and WebSocket connections for collaboration). This means:

• No server-side data storage: Drawings live in the browser unless explicitly exported
• Collaboration data is transient: The room server relays messages but doesn’t persist them
• Authentication: Excalidraw has no built-in auth. Use your reverse proxy to add basic auth or integrate with Authelia/Authentik if you want to restrict access

For internal team use behind a VPN or SSO, this is usually fine. For public-facing deployments, add an auth layer.

Conclusion

Excalidraw is one of the easiest self-hosted apps you’ll ever deploy — a single container, no database, minimal configuration. Yet it delivers a genuinely excellent diagramming experience that rivals (and often beats) commercial tools like Miro or Lucidchart for technical diagrams.

The hand-drawn aesthetic isn’t just cute — it actually makes diagrams feel more approachable and less “final,” which encourages iteration. Combined with real-time collaboration on your own infrastructure, it’s a must-have for any home lab or team toolkit.

Pair it with Nginx Proxy Manager for easy HTTPS, and you’ve got a private whiteboard ready for your next architecture review.