TDvorak/Excalidraw
1
0
Fork 0
mirror of https://github.com/Dvorinka/excalidraw-full.git synced 2026-06-04 22:32:55 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update README and docker-compose; add Chinese README

Browse Source 
Expanded and clarified the main README with new features, configuration, and deployment instructions. Added a Chinese translation (README_zh.md). Updated docker-compose.yml to improve volume and env file mounting.
This commit is contained in:
Yuzhong Zhang
2025-07-06 16:02:39 +08:00
parent 7083d04fbf
commit a7c4624e70
3 changed files with 248 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+108 -69
View File
@@ -1,43 +1,103 @@
# Excalidraw Complete: A Self-Hosted Solution # Excalidraw Complete: Your Self-Hosted, Cloud-Ready Collaboration Platform
Excalidraw Complete simplifies the deployment of Excalidraw, bringing an ![README-zh](./README_zh.md)
all-in-one solution to self-hosting this versatile virtual whiteboard. Designed
for ease of setup and use, Excalidraw Complete integrates essential features
into a single Go binary. This solution encompasses:
- The intuitive Excalidraw frontend UI for seamless user experience. Excalidraw Complete has evolved. It's no longer just a simple wrapper for Excalidraw, but a powerful, self-hosted collaboration platform with a "Bring Your Own Cloud" (BYOC) philosophy. It provides user authentication, multi-canvas management, and the unique ability to connect directly to your own cloud storage from the frontend.
- An integrated data layer ensuring fast and efficient data handling based on different data providers.
- A socket.io implementation to enable real-time collaboration among users.
The project goal is to alleviate the setup complexities traditionally associated with self-hosting Excalidraw, especially in scenarios requiring data persistence and collaborative functionalities. The core idea is to let the backend handle user identity while giving you, the user, full control over where your data is stored.
## Installation ## Key Features
To get started, download the latest release binary: - **GitHub Authentication**: Secure sign-in using GitHub OAuth.
- **Multi-Canvas Management**: Users can create, save, and manage multiple drawing canvases.
- **Flexible Data Storage (BYOC)**:
- **Default Backend Storage**: Out-of-the-box support for saving canvases on the server's storage (SQLite, Filesystem, S3).
- **Direct Cloud Connection**: The frontend can connect directly to your own cloud services like **Cloudflare KV** or **Amazon S3** for ultimate data sovereignty. Your credentials never touch our server.
- **Real-time Collaboration**: The classic Excalidraw real-time collaboration is fully supported.
- **Secure OpenAI Proxy**: An optional backend proxy for using OpenAI's GPT-4 Vision features, keeping your API key safe.
- **All-in-One Binary**: The entire application, including the patched frontend and backend server, is compiled into a single Go binary for easy deployment.
## Frontend Canvas Storage Strategies
- **IndexedDB**: A fast, secure, and scalable key-value store. No need to configure anything. Not login required.
- **Backend Storage**: The backend can save the canvas to the server's storage (SQLite, Filesystem, S3). Synchronized in different devices.
- **Cloudflare KV**: A fast, secure, and scalable key-value store. Need to setup cloudlfare worker and DO spaces.
- **Amazon S3**: A reliable, scalable, and inexpensive object storage service.
## Installation & Running
One Click Docker run [Excalidraw-Full](https://github.com/BetterAndBetterII/excalidraw-full).
```bash ```bash
# Visit https://github.com/PatWie/excalidraw-complete/releases/ for the download URL # Example for Linux
wget <binary-download-url> git clone https://github.com/BetterAndBetterII/excalidraw-full.git
chmod +x excalidraw-complete cd excalidraw-full
./excalidraw-complete touch ./excalidraw.db # IMPORTANT: Initialize the SQLite DB, OTHERWISE IT WILL NOT START
docker compose up -d
``` ```
Once launched, Excalidraw Complete is accessible at `localhost:3002`, ready for The server will start, and you can access the application at `http://localhost:3002`.
drawing and collaboration.
### Configuration ## Configuration
Excalidraw Complete adapts to your preferences with customizable storage solutions, adjustable via the `STORAGE_TYPE` environment variable: Configuration is managed via environment variables. For a full template, see the `.env.example` section below.
- **Filesystem:** Opt for `STORAGE_TYPE=filesystem` and define `LOCAL_STORAGE_PATH` to use a local directory. ### 1. Backend Configuration (Required)
- **SQLite:** Select `STORAGE_TYPE=sqlite` with `DATA_SOURCE_NAME` for local SQLite storage, including the option for `:memory:` for ephemeral data.
- **AWS S3:** Choose `STORAGE_TYPE=s3` and specify `S3_BUCKET_NAME` to leverage S3 bucket storage, ideal for cloud-based solutions.
These flexible configurations ensure Excalidraw Complete fits seamlessly into your existing setup, whether on-premise or in the cloud. You must configure GitHub OAuth and a JWT secret for the application to function.
- `GITHUB_CLIENT_ID`: Your GitHub OAuth App's Client ID.
- `GITHUB_CLIENT_SECRET`: Your GitHub OAuth App's Client Secret.
- `GITHUB_REDIRECT_URL`: The callback URL. For local testing, this is `http://localhost:3002/auth/github/callback`.
- `JWT_SECRET`: A strong, random string for signing session tokens. Generate one with `openssl rand -base64 32`.
- `OPENAI_API_KEY`: Your secret key from OpenAI.
- `OPENAI_BASE_URL`: (Optional) For using compatible APIs like Azure OpenAI.
### 2. Default Storage (Optional, but Recommended)
This configures the server's built-in storage, used by default.
- `STORAGE_TYPE`: `memory` (default), `sqlite`, `filesystem`, or `s3`.
- `DATA_SOURCE_NAME`: Path for the SQLite DB (e.g., `excalidraw.db`).
- `LOCAL_STORAGE_PATH`: Directory for filesystem storage.
- `S3_BUCKET_NAME`, `AWS_REGION`, etc.: For S3 storage.
### 3. OpenAI Proxy (Optional)
To enable AI features, set your OpenAI API key.
- `OPENAI_API_KEY`: Your secret key from OpenAI.
- `OPENAI_BASE_URL`: (Optional) For using compatible APIs like Azure OpenAI.
### 4. Frontend Configuration
Frontend storage adapters (like Cloudflare KV, S3) are configured directly in the application's UI settings after you log in. This is by design: your private cloud credentials are only ever stored in your browser's session and are never sent to the backend server.
### Example `.env.example`
Create a `.env` file in the project root and add the following, filling in your own values.
```env
# Backend Server Configuration
# Get from https://github.com/settings/developers
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GITHUB_REDIRECT_URL=http://localhost:3002/auth/github/callback
# Generate with: openssl rand -base64 32
JWT_SECRET=your_super_secret_jwt_string
# Default Storage (SQLite)
STORAGE_TYPE=sqlite
DATA_SOURCE_NAME=excalidraw.db
# Optional OpenAI Proxy
OPENAI_API_KEY=sk-your_openai_api_key
```
## Building from Source ## Building from Source
Interested in contributing or customizing? Build Excalidraw Complete from source with these steps: The process is similar to before, but now requires the Go backend to be built.
### Using Docker (Recommended) ### Using Docker (Recommended)
@@ -46,56 +106,35 @@ Interested in contributing or customizing? Build Excalidraw Complete from source
git clone https://github.com/PatWie/excalidraw-complete.git --recursive git clone https://github.com/PatWie/excalidraw-complete.git --recursive
cd excalidraw-complete cd excalidraw-complete
# Build the Docker image (includes frontend and backend) # Build the Docker image
# This handles the frontend build, patching, and Go backend compilation.
docker build -t excalidraw-complete -f excalidraw-complete.Dockerfile . docker build -t excalidraw-complete -f excalidraw-complete.Dockerfile .
# Run the container # Run the container, providing the environment variables
docker run -p 3002:3002 excalidraw-complete docker run -p 3002:3002 \
-e GITHUB_CLIENT_ID="your_id" \
-e GITHUB_CLIENT_SECRET="your_secret" \
-e GITHUB_REDIRECT_URL="http://localhost:3002/auth/github/callback" \
-e JWT_SECRET="your_jwt_secret" \
-e STORAGE_TYPE="sqlite" \
-e DATA_SOURCE_NAME="excalidraw.db" \
-e OPENAI_API_KEY="your_openai_api_key" \
excalidraw-complete
``` ```
### Manual Build ### Manual Build
```bash 1. **Build Frontend**: Follow the steps in the original README to patch and build the Excalidraw frontend inside the `excalidraw/` submodule.
# Clone and prepare the Excalidraw frontend 2. **Copy Frontend**: Ensure the built frontend from `excalidraw/excalidraw-app/build` is copied to the `frontend/` directory in the root.
git clone https://github.com/PatWie/excalidraw-complete.git --recursive 3. **Build Go Backend**:
cd ./excalidraw-complete/excalidraw ```bash
go build -o excalidraw-complete main.go
# Apply frontend patches ```
git apply ../frontend.patch 4. **Run**:
```bash
# Build frontend # Set environment variables first
npm install ./excalidraw-complete
cd excalidraw-app ```
npm run build:app:docker
cd ../../
# Copy frontend build to correct location
cp -r excalidraw/excalidraw-app/build frontend/
# Build Go application
go build -o excalidraw-complete main.go
```
(Optional) Replace `localhost:3002` inside of `main.go` with your domain name if you want to use a reverse proxy
(Optional) Replace `"ssl=!0", "ssl=0"` with `"ssl=!0", "ssl=1"` if you want to use HTTPS
(Optional) Replace `"ssl:!0", "ssl:0"` with `"ssl:!0", "ssl:1"` if you want to use HTTPS
Declare environment variables if you want any (see section above)
Example: `STORAGE_TYPE=sqlite DATA_SOURCE_NAME=/tmp/excalidb.sqlite`
Start the server:
```bash
go run main.go --listen=":3002"
STORAGE_TYPE=sqlite DATA_SOURCE_NAME=test.db go run main.go --loglevel debug --listen=":3002"
STORAGE_TYPE=filesystem LOCAL_STORAGE_PATH=/tmp/excalidraw/ go run main.go --loglevel debug --listen=":3002"
```
Excalidraw Complete is now running on your machine, ready to bring your collaborative whiteboard ideas to life.
--- ---
Excalidraw is a fantastic tool, but self-hosting it can be tricky. I welcome Excalidraw is a fantastic tool. This project aims to make a powerful, data-secure version of it accessible to everyone. Contributions are welcome!
your contributions to improve Excalidraw Complete — be it through adding new
features, improving existing ones, or bug reports.
README_zh.md
+138
View File
@@ -0,0 +1,138 @@
# Excalidraw Complete: 您的自托管、云就绪协作平台
Excalidraw Complete 已经进化。它不再仅仅是 Excalidraw 的一个简单封装，而是一个强大的、自托管的协作平台，秉承"自带云"（BYOC - Bring Your Own Cloud）的理念。它提供用户认证、多画板管理，以及从前端直接连接到您自己的云存储的独特能力。
其核心思想是让后端处理用户身份，同时让您（用户）完全控制数据的存储位置。
## 主要特性
- **GitHub 认证**：使用 GitHub OAuth 安全登录。
- **多画板管理**：用户可以创建、保存和管理多个绘图画板。
- **灵活的数据存储 (BYOC)**：
- **默认后端存储**：开箱即用地支持将画板保存在服务器的存储中（SQLite、文件系统、S3）。
- **直接云连接**：前端可以直接连接到您自己的云服务，如 **Cloudflare KV** 或 **Amazon S3**，以实现终极数据主权。您的凭证永远不会触及我们的服务器。
- **实时协作**：完全支持经典的 Excalidraw 实时协作功能。
- **安全的 OpenAI 代理**：一个可选的后端代理，用于使用 OpenAI 的 GPT-4 Vision 功能，确保您的 API 密钥安全。
- **一体化二进制文件**：整个应用程序，包括打过补丁的前端和后端服务器，都被编译成一个单一的 Go 二进制文件，便于部署。
## 前端画板存储策略
- **IndexedDB**: 一种快速、安全且可扩展的键值存储。无需任何配置，也无需登录。
- **后端存储**: 后端可以将画板保存到服务器的存储中（SQLite、文件系统、S3）。可在不同设备间同步。
- **Cloudflare KV**: 一种快速、安全且可扩展的键值存储。需要设置 Cloudflare Worker 和 DO Spaces。
- **Amazon S3**: 一种可靠、可扩展且经济的对象存储服务。
## 安装与运行
一键 Docker 运行 [Excalidraw-Full](https://github.com/BetterAndBetterII/excalidraw-full).
```bash
# Linux 示例
git clone https://github.com/BetterAndBetterII/excalidraw-full.git
cd excalidraw-full
touch ./excalidraw.db # 重要：初始化 SQLite 数据库，否则无法启动
docker compose up -d
```
服务器将启动，您可以在 `http://localhost:3002` 访问该应用。
## 配置
配置通过环境变量进行管理。有关完整模板，请参阅下面的 `.env.example` 部分。
### 1. 后端配置 (必需)
您必须配置 GitHub OAuth 和 JWT 密钥才能使应用程序正常运行。
- `GITHUB_CLIENT_ID`: 您的 GitHub OAuth App 的 Client ID。
- `GITHUB_CLIENT_SECRET`: 您的 GitHub OAuth App 的 Client Secret。
- `GITHUB_REDIRECT_URL`: 回调 URL。对于本地测试，这是 `http://localhost:3002/auth/github/callback`。
- `JWT_SECRET`: 用于签署会话令牌的强随机字符串。使用 `openssl rand -base64 32` 生成一个。
- `OPENAI_API_KEY`: 您在 OpenAI 的秘密密钥。
- `OPENAI_BASE_URL`: (可选) 用于使用兼容的 API，如 Azure OpenAI。
### 2. 默认存储 (可选，但推荐)
这会配置服务器的内置存储，默认使用。
- `STORAGE_TYPE`: `memory` (默认), `sqlite`, `filesystem`, 或 `s3`。
- `DATA_SOURCE_NAME`: SQLite 数据库的路径 (例如, `excalidraw.db`)。
- `LOCAL_STORAGE_PATH`: 文件系统存储的目录。
- `S3_BUCKET_NAME`, `AWS_REGION`, 等: 用于 S3 存储。
### 3. OpenAI 代理 (可选)
要启用 AI 功能，请设置您的 OpenAI API 密钥。
- `OPENAI_API_KEY`: 您在 OpenAI 的秘密密钥。
- `OPENAI_BASE_URL`: (可选) 用于使用兼容的 API，如 Azure OpenAI。
### 4. 前端配置
前端存储适配器（如 Cloudflare KV, S3）在您登录后直接在应用程序的 UI 设置中配置。这是特意设计的：您的私有云凭证只存储在浏览器的会话中，绝不会发送到后端服务器。
### `.env.example` 示例
在项目根目录中创建一个 `.env` 文件，并添加以下内容，填入您自己的值。
```env
# 后端服务器配置
# 从 https://github.com/settings/developers 获取
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GITHUB_REDIRECT_URL=http://localhost:3002/auth/github/callback
# 使用以下命令生成: openssl rand -base64 32
JWT_SECRET=your_super_secret_jwt_string
# 默认存储 (SQLite)
STORAGE_TYPE=sqlite
DATA_SOURCE_NAME=excalidraw.db
# 可选的 OpenAI 代理
OPENAI_API_KEY=sk-your_openai_api_key
```
## 从源码构建
过程与之前类似，但现在需要构建 Go 后端。
### 使用 Docker (推荐)
```bash
# 克隆仓库及其子模块
git clone https://github.com/PatWie/excalidraw-complete.git --recursive
cd excalidraw-complete
# 构建 Docker 镜像
# 此过程会处理前端构建、打补丁和 Go 后端编译。
docker build -t excalidraw-complete -f excalidraw-complete.Dockerfile .
# 运行容器，并提供环境变量
docker run -p 3002:3002 \
-e GITHUB_CLIENT_ID="your_id" \
-e GITHUB_CLIENT_SECRET="your_secret" \
-e GITHUB_REDIRECT_URL="http://localhost:3002/auth/github/callback" \
-e JWT_SECRET="your_jwt_secret" \
-e STORAGE_TYPE="sqlite" \
-e DATA_SOURCE_NAME="excalidraw.db" \
-e OPENAI_API_KEY="your_openai_api_key" \
excalidraw-complete
```
### 手动构建
1. **构建前端**: 按照原始 README 中的步骤，在 `excalidraw/` 子模块内打补丁并构建 Excalidraw 前端。
2. **复制前端**: 确保将 `excalidraw/excalidraw-app/build` 中构建好的前端文件复制到根目录的 `frontend/` 目录下。
3. **构建 Go 后端**:
```bash
go build -o excalidraw-complete main.go
```
4. **运行**:
```bash
# 首先设置环境变量
./excalidraw-complete
```
---
Excalidraw 是一个很棒的工具。该项目旨在让每个人都能使用一个功能强大、数据安全的版本。欢迎贡献！
docker-compose.yml
+2 -3
View File
@@ -7,6 +7,5 @@ services:
- "3002:3002" - "3002:3002"
volumes: volumes:
- ./data:/root/data - ./data:/root/data
- ./excalidraw.db:/root/excalidraw.db - ./excalidraw.db:/root/excalidraw.db:Z
env_file: - ./.env:/root/.env
- .env