Excalidraw (self-host)

What is Excalidraw (self-host)?

Excalidraw is an open-source virtual whiteboard application distributed under the MIT license that renders technical diagrams with an organic, hand-drawn aesthetic. Designed to solve the friction of overly rigid diagramming platforms, it provides software engineers, system designers, and product managers with an immediate canvas for sketching low-fidelity schematics. The application accepts vector inputs such as freehand pen strokes, geometric shapes, text boxes, and directional arrows. It converts these inputs into structured JavaScript objects that render on an HTML5 canvas element using customizable stroke styling, fill patterns, and rough edge algorithms, outputting vectorized SVG assets or rasterized PNG files. First, the application uses stroke randomization engine capabilities to transform perfect geometric primitives into sketchy, human-like line drawings. Second, it includes a JSON-based element model that enables lossless file storage, programmatic generation of diagrams, and clipboard pasting of canvas elements across sessions. Third, it provides customizable shape libraries for architecture cloud icons, including AWS, GCP, and Kubernetes components. Compared to commercial options like Lucidchart or Miro, self-hosting this software grants complete operational governance over visual assets. Organizations retain full control over data transit without relying on external cloud infrastructure for image hosting.

How it works

At its core, Excalidraw leverages the Rough.js rendering library to draw sketchy graphics on the HTML5 Canvas API. When a user creates an object, such as a 200 by 100 pixel rectangle, the engine does not draw straight vector paths. Instead, it calculates multiple slightly jittered Bezier curves between the specified vertex coordinates using pseudorandom generator seeds. Consider drawing a simple flowchart node. The user selects the rectangle tool and drags from coordinate (X: 50, Y: 50) to (X: 250, Y: 150). The application registers a JSON payload containing the shape type, dimensions, stroke color (#1e1e1e), fill style (hachure), and seed value (1849204). Rough.js computes two offset line passes per side to recreate the visual inconsistency of human pencil strokes. The application front-end is built as a single-page React application written in TypeScript and bundled using Vite. Static web assets are served through any web server, such as Nginx or Caddy, or wrapped inside a lightweight Docker container operating on Alpine Linux. Data flow operates entirely within client memory using Zustand for application state management and IndexedDB for local persistence. When real-time collaboration is enabled, client instances transmit delta operations using WebSockets to a lightweight relay server running WebSocket protocols, ensuring state synchronization without modifying original scene histories.

How to use it

1. 1Step 1: Pull the official container image by executing `docker pull excalidraw/excalidraw:latest` in your terminal environment. Step 2: Launch the container with `docker run -d -p 8080:80 --name excalidraw excalidraw/excalidraw:latest` to bind the web server to host port 8080. Step 3: Open a browser and navigate to `http://localhost:8080` to verify the application loads correctly.
2. 2Step 4: Press key `R` to select the Rectangle tool, then click and drag on the canvas to draw a 300 by 150 pixel box. Step 5: Double-click inside the newly created box and enter the label text 'API Gateway'. Step 6: Press `Ctrl+S` or click the export icon in the upper-left menu, choose 'PNG', set scale factor to '2x', and click 'Export to PNG' to save the file.
3. 3A frequent deployment mistake occurs when administrators deploy the static container without configuring environment variables for backend socket relay servers. If the `VITE_APP_WS_SERVER_URL` variable is omitted during custom build steps, session sharing controls fail silently when users initiate collaborative links.
4. 4To achieve optimal canvas performance, avoid building scenes exceeding 3,000 distinct vector elements on low-memory client hardware. If you need to construct massive database schemas, break the workspace into smaller modular `.excalidraw` files and hyperlink them together using text object annotations.

What it can do

• Utility

Use cases

Assumptions and limitations

Understanding the result

Virtual whiteboard for sketching hand-drawn diagrams.

Tool details

More diagram

References

• /excalidraw-whiteboard — GitHub Repository

  Upstream project · GitHub

• MIT License

  Upstream project

Frequently asked