A fully self-hosted, feature-rich fork of Excalidraw with real-time collaboration, user workspaces, video recordings, presentation mode, and more.
Warning
This is a hobby project in active development. I created AstraDraw because I wanted to share some of my Obsidian whiteboards with my team — while keeping the files local in my vault. Inspired by the excellent Obsidian Excalidraw Plugin by @zsviczian.
A few things to keep in mind:
- 🤖 Most code is AI-assisted (written with Cursor)
- 👤 Solo developer — no team behind this, just me working in spare time
⚠️ Expect bugs and breaking changes as the project evolves
That said, it works for my use case and I'm actively improving it. If you find this useful, contributions are very welcome! 🙌
The end goal is to selectively sync .excalidraw files from your Obsidian vault to a self-hosted AstraDraw instance (via Syncthing, mounted volumes, or similar). The synced boards appear in your private workspace, where you can share specific boards with different teams using AstraDraw's role-based access control. All changes sync back to your Obsidian vault — your vault remains the source of truth, AstraDraw becomes the collaboration layer.
Not yet implemented — focusing on core features first.
AstraDraw extends the open-source Excalidraw whiteboard with enterprise-ready features while remaining fully self-hostable. It's designed for teams and organizations that need:
- User authentication via OIDC (Authentik, Keycloak, Dex) or local accounts
- Workspaces with teams, collections, and role-based access (Admin/Member/Viewer)
- Real-time collaboration with presence indicators and cursor tracking
- Threaded comments with @mentions and real-time sync
- In-app notifications for mentions and comment replies
- Video walkthroughs (Talktrack) with camera picture-in-picture
- Presentation mode using frames as slides with laser pointer
- Custom pen presets (highlighter, fountain, marker, etc.)
- Quick search (Cmd+K) to find scenes across workspaces
- GIF/Sticker search via GIPHY integration
- 🎨 Infinite canvas with hand-drawn style
- 🔒 End-to-end encryption for all scene data
- 🤝 Real-time collaboration via WebSocket
- 📱 Responsive design for desktop and mobile
- 🌙 Dark mode support
| Feature | Description | Documentation |
|---|---|---|
| Workspaces | Personal & shared workspaces with scene organization | docs/features/WORKSPACE.md |
| Roles & Teams | Role-based access (Admin/Member/Viewer), team management | docs/guides/ROLES_TEAMS_COLLECTIONS.md |
| Collaboration | Real-time collaboration with presence & cursor tracking | docs/features/COLLABORATION.md |
| Comments | Threaded canvas comments with @mentions | docs/features/COMMENTS.md |
| Notifications | In-app notifications for mentions and replies | docs/features/NOTIFICATIONS.md |
| Talktrack | Record canvas walkthroughs with camera PIP | docs/features/TALKTRACK.md |
| Presentation | Use frames as slides with laser pointer | docs/features/PRESENTATION_MODE.md |
| Custom Pens | Highlighter, fountain, marker presets | docs/features/PENS_IMPLEMENTATION.md |
| Quick Search | Cmd+K to search scenes across workspaces | docs/features/QUICK_SEARCH.md |
┌─────────────────────────────────────────────────────────────────────┐
│ Traefik Proxy (HTTPS) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
│ │ / │ │ /socket.io/ │ │ /api/v2/ │ │
│ │ Frontend │ │ Room Server │ │ Backend API │ │
│ └──────────────┘ └──────────────┘ └──────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────┐
│ React + Vite │ │ Socket.io │ │ NestJS + Prisma │
│ Excalidraw Fork │ │ Collaboration │ │ - Auth (OIDC/Local) │
│ │ │ │ │ - Workspace API │
│ │ │ │ │ - Storage (S3/MinIO) │
└─────────────────┘ └─────────────────┘ └─────────────────────────────┘
│
┌───────────────────────┴───────────────────┐
▼ ▼
┌─────────────────────┐ ┌─────────────────────┐
│ PostgreSQL │ │ MinIO/S3 │
│ (Users, Scenes, │ │ (Scene data, │
│ Metadata) │ │ Files, Rooms) │
└─────────────────────┘ └─────────────────────┘
AstraDraw consists of multiple repositories:
| Repository | Description |
|---|---|
| astradraw | Main orchestration (this repo) - deployment, docs |
| astradraw-app | React frontend (Excalidraw fork) |
| astradraw-api | NestJS backend API |
| astradraw-room | WebSocket collaboration server |
astradraw/
├── frontend/ # React app (clone astradraw-app here)
├── backend/ # NestJS API (clone astradraw-api here)
├── room-service/ # WebSocket server (clone astradraw-room here)
├── docs/ # Documentation
├── deploy/ # Docker Compose, configs
└── Justfile # Development commands
# 1. Clone all repositories
git clone https://github.com/AstraDraw/astradraw.git
cd astradraw
git clone https://github.com/AstraDraw/astradraw-app.git frontend
git clone https://github.com/AstraDraw/astradraw-api.git backend
git clone https://github.com/AstraDraw/astradraw-room.git room-service
# 2. Setup (first time only)
just setup
# 3. Start development with hot-reload
just dev
# 4. Access at https://draw.local# 1. Clone this repository
git clone https://github.com/AstraDraw/astradraw.git
cd astradraw/deploy
# 2. Copy environment template
cp env.example .env
# 3. Create secrets
mkdir -p secrets
openssl rand -base64 32 > secrets/jwt_secret
openssl rand -base64 32 > secrets/postgres_password
echo "minioadmin" > secrets/minio_access_key
openssl rand -base64 32 > secrets/minio_secret_key
# 4. Generate self-signed certs for local testing
mkdir -p certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout certs/server.key -out certs/server.crt \
-subj "/CN=draw.local"
# 5. Start all services
docker compose up -d
# 6. Access at https://draw.local (add to /etc/hosts if needed)Copy deploy/env.example to deploy/.env and configure:
| Variable | Description |
|---|---|
APP_DOMAIN |
Your domain (e.g., draw.example.com) |
APP_PROTOCOL |
http or https |
POSTGRES_* |
PostgreSQL credentials |
OIDC_* |
OIDC provider settings (optional) |
GIPHY_API_KEY |
For Stickers & GIFs sidebar |
- Local Auth (default): Email/password with admin account
- OIDC/SSO: Authentik, Keycloak, Dex, or any OIDC provider
- Hybrid: Both local and SSO enabled
See docs/deployment/SSO_OIDC_SETUP.md for detailed auth setup.
All sensitive variables support the _FILE suffix pattern for Docker secrets:
environment:
- JWT_SECRET_FILE=/run/secrets/jwt_secretSee docs/deployment/DOCKER_SECRETS.md for details.
| Document | Description |
|---|---|
| docs/README.md | Full documentation index |
| CONTRIBUTING.md | Development setup guide |
| docs/architecture/ARCHITECTURE.md | Technical architecture |
| docs/deployment/ | Deployment guides |
Frontend: React 18, TypeScript, Vite, Jotai, SCSS
Backend: NestJS, Prisma, PostgreSQL, MinIO/S3, JWT
Infrastructure: Docker Compose, Traefik, Let's Encrypt
We welcome contributions! Please see CONTRIBUTING.md for development setup.
Note: All issues should be filed in this repository, not in the sub-repos.
AstraDraw is built on the shoulders of giants:
- Excalidraw - The amazing open-source whiteboard (MIT License)
- excalidraw-room - Official collaboration server (MIT License)
- excalidraw-storage-backend - Storage backend foundation (MIT License)
- Obsidian Excalidraw Plugin - Inspiration for pens and presentation mode
MIT License - see LICENSE for details.
This project includes code from:
- Excalidraw © 2020 Excalidraw (MIT License)
- excalidraw-storage-backend © 2022 Kilian Decaderincourt (MIT License)