Skip to content

README.md

Latest commit

 

History

History
138 lines (100 loc) · 3.9 KB

README.md

File metadata and controls

138 lines (100 loc) · 3.9 KB

excalidraw-persistent

A minimal self-hosted whiteboard built on top of the open-source @excalidraw/excalidraw package.

The board state is persisted server-side (on disk), so your drawings survive browser refreshes, cache clears, and are consistent across all your devices.

Disclaimer: This project is unofficial and not affiliated with or endorsed by the Excalidraw team.

Features

  • 🎨 Full Excalidraw experience
  • 🔒 Password protection — board is private behind a session cookie
  • 💾 Auto-save after changes
  • 🗄 Automatic compressed backups (gzip) on a configurable cron schedule
  • 📦 Single Docker container (Next.js fullstack)
  • 🗂 State persisted to disk

What this is not

  • Not a collaboration tool (single user, single board)
  • Not Excalidraw+ (no cloud sync, no multiplayer, no paid features)
  • Not officially supported by the Excalidraw team

Getting started

With Docker

docker run -d \
  --name excalidraw-persistent \
  -p 3004:3004 \
  -v ./data:/app/data \
  -e BOARD_PASSWORD=your-password-here \
  -e SECRET=your-secret-here \
  ghcr.io/malopolese/excalidraw-persistent:latest

Then open http://localhost:3004.

With Docker Compose

services:
  excalidraw:
    image: ghcr.io/malopolese/excalidraw-persistent:latest
    container_name: excalidraw-persistent
    restart: unless-stopped
    ports:
      - "3004:3004"
    volumes:
      - ./data:/app/data
    environment:
      BOARD_PASSWORD: your-password-here
      SECRET: your-secret-here
      BACKUP_CRON: "0 2 * * *" # every day at 2am
      BACKUP_KEEP: "7" # keep last 7 backups
docker compose up -d

Environment variables

Variable Required Default Description
BOARD_PASSWORD ✅ — Password to access the board
SECRET ✅ — Random string for signing session cookies
BACKUP_CRON ❌ 0 2 * * * Backup schedule in cron format
BACKUP_KEEP ❌ 7 Number of compressed backups to keep

Generate a secure SECRET with:

openssl rand -hex 32

Development

git clone https://github.com/MaloPolese/excalidraw-persistent.git
cd excalidraw-persistent
npm install
npm run dev

Open http://localhost:3000.

How it works

  • Frontend: Excalidraw React component loaded client-side only (no SSR)
  • Backend: Next.js API route (GET /api/board / POST /api/board)
  • Auth: Password checked on login, session stored in a signed httpOnly cookie (7 days)
  • Storage: Board state saved as data/board.json on disk
  • Auto-save: Debounced 300ms after last change.
  • Backups: Runs on a cron schedule via node-cron, compresses board.json with gzip, stored in data/backups/. Old backups are rotated automatically.

Backup cron examples

Expression Meaning
* * * * * Every minute
0 * * * * Every hour
0 */2 * * * Every 2 hours
0 2 * * * Every day at 2am (default)
0 2 */2 * * Every 2 days at 2am
0 2 * * 0 Every Sunday at 2am

Restoring a backup

# On your server, in the data/ folder
gunzip -c backups/board.backup.2026-03-28-02-00.json.gz > board.json
# Then restart the container
docker compose restart excalidraw

Credits

This project uses @excalidraw/excalidraw, which is MIT licensed.

License

MIT — see LICENSE