From 718f50ef10daa2b7e4d9367dae5e088668bb84f0 Mon Sep 17 00:00:00 2001 From: yiling Date: Tue, 16 Jun 2026 14:53:03 +0800 Subject: [PATCH] docs: add temporal deploy guide and link from quickstart --- docs/configuration/temporal.mdx | 82 +++++++++++++++++++++++++++++ docs/docs.json | 2 +- docs/getting-started/overview.mdx | 3 +- docs/getting-started/quickstart.mdx | 4 ++ 4 files changed, 88 insertions(+), 3 deletions(-) create mode 100644 docs/configuration/temporal.mdx diff --git a/docs/configuration/temporal.mdx b/docs/configuration/temporal.mdx new file mode 100644 index 00000000..f50da97c --- /dev/null +++ b/docs/configuration/temporal.mdx @@ -0,0 +1,82 @@ +--- +title: Deploy with Temporal +description: Configure a high-scale production deployment using Temporal and S3-compatible storage. +--- + +For production environments or workloads with high-volume video processing and heavy AI agent usage, running background tasks on a single server can cause bottlenecks. Shumai resolves this by offloading task queue management, retries, and background executions to **Temporal**. + +This allows you to decouple workloads and run specialized worker nodes on separate, dedicated machines. + +--- + +## How it Works + +When configured for Temporal, the core Shumai web application does not process background jobs itself. Instead, it publishes tasks to a Temporal Cluster queue. + +```mermaid +graph TD + UserUpload[User Uploads Video] --> WebApp[Shumai Web UI / API] + WebApp -->|Register Task| Temporal[Temporal Cluster] + Temporal -->|Queue: Transcoding| TranscodeWorker[Transcode Worker Machine] + Temporal -->|Queue: AI Agents| AgentWorker[Agent Worker Machine] +``` + +- **Transcoding Workers**: Can be run on GPU-accelerated or high-CPU compute instances. +- **AI Agent Workers**: Can be run on isolated, sandboxed hosts to safely execute automation scripts. + +> [!IMPORTANT] +> **Storage Requirement**: Because the core application and the background workers run on separate machines in a distributed setup, **you must configure an S3-compatible storage backend** (such as AWS S3, Cloudflare R2, or MinIO). Local storage (`STORAGE_BACKEND=local`) is not supported in this mode because the workers and the web application do not share a common filesystem. + +--- + +## Step 1: Deploy the Core Stack + +On your primary host machine, spin up the database, Temporal cluster services, and the main Shumai web application: + +1. **Download the Temporal Stack Configuration**: + ```bash + curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/temporal/docker-compose.yaml + ``` +2. **Configure S3 Settings**: + Open the `docker-compose.yaml` file and set your S3 credentials and endpoint environment variables under the `shumai` service. +3. **Start the Services**: + ```bash + docker compose up -d + ``` + This exposes the web application on port `3000`, the database on `5432`, the Temporal gRPC service on `7233`, and the Temporal management dashboard on `8080`. + +--- + +## Step 2: Configure & Run Workers + +On your specialized worker machines, you will run the dedicated background worker services. Each worker requires a `.env` file referencing the database, S3 storage, and the Temporal cluster: + +```env +DATABASE_URL=postgresql://shumai:shumai_password@:5432/shumai_db?schema=public +WORKFLOW_EXECUTOR=temporal +TEMPORAL_ADDRESS=:7233 +STORAGE_BACKEND=s3 +AWS_ENDPOINT_URL_S3=https://your-s3-endpoint.com +S3_BUCKET=shumai +S3_REGION=us-east-1 +S3_ACCESS_KEY_ID=your-access-key-id +S3_SECRET_ACCESS_KEY=your-secret-access-key +``` + +### Media Transcoding Worker + +Run this on your media processing nodes (requires system installations of `ffmpeg` and `ffprobe`): + +```bash +npm install -g @shumai-one/shumai-transcode +shumai-transcode +``` + +### AI Agent Worker + +Run this on your sandboxed agent execution nodes (requires sandbox dependencies like `bubblewrap` or `sandbox-exec`): + +```bash +npm install -g @shumai-one/shumai-agent +shumai-agent +``` diff --git a/docs/docs.json b/docs/docs.json index e508b6fc..07ce8383 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -51,7 +51,7 @@ }, { "group": "Configuration", - "pages": ["configuration/env-variables"] + "pages": ["configuration/env-variables", "configuration/temporal"] } ] } diff --git a/docs/getting-started/overview.mdx b/docs/getting-started/overview.mdx index c15509af..0f9cd05f 100644 --- a/docs/getting-started/overview.mdx +++ b/docs/getting-started/overview.mdx @@ -7,8 +7,7 @@ description: Learn about Shumai, a modern collaboration and media review platfor **Shumai** is a self-hosted media collaboration platform designed for creative teams, video editors, designers, and clients. It provides a centralized workspace where you can upload, organize, and review assets (video, audio, images, and documents) in real-time. With built-in AI capabilities and background transcoding, Shumai helps streamline asset organization and feedback workflows. -![Shumai Dashboard Overview Placeholder](https://placehold.co/800x450/2C2E3E/D95A66?text=Shumai+Dashboard+Overview) -_Placeholder: Dashboard view showing the file explorer, active projects, and sidebar options._ +![Shumai Dashboard](/screenshot.webp) --- diff --git a/docs/getting-started/quickstart.mdx b/docs/getting-started/quickstart.mdx index 95fd80ba..df574e47 100644 --- a/docs/getting-started/quickstart.mdx +++ b/docs/getting-started/quickstart.mdx @@ -22,6 +22,10 @@ Docker Compose automatically configures and spins up all required services (the 3. **Access the Dashboard**: Open your browser and navigate to **`http://localhost:3000`** to access the Shumai Web UI. +### Production Deployments (Temporal) + +If you are deploying Shumai for a production team with high-volume video uploads, we recommend setting up a distributed deployment using **Temporal** and an S3-compatible storage backend. This offloads resource-heavy video transcoding and AI agents to separate, dedicated worker nodes to keep your main dashboard fast and responsive. For setup instructions, see the [Deploy with Temporal](/configuration/temporal) guide. + --- ## Option 2: Install via NPM