mirror of
https://github.com/shumaiOne/shumai.git
synced 2026-11-22 05:09:30 +00:00
* refactor(agent)!: migrate sessions to Pi Durable Replace patched AgentHarness storage with per-session SQLite and PostgreSQL commit mirroring. Migrate legacy history automatically and run agent queues with the main server. BREAKING CHANGE: Remove standalone agent workers and return native Pi entry records from chat history APIs. * fix(agent): constrain session log dialog scrolling Keep the header visible and wrap long output while log entries and expanded records scroll within the dialog. Cover desktop and narrow viewports through the dashboard Sessions flow. * fix(agent): hide entry IDs from session log card headers Retain internal entry IDs in expanded raw records for debugging. Verify that card headers omit the IDs while raw JSON preserves them. * test(e2e): handle browser wheel limits in session log checks Verify that a normal wheel event moves the viewport before explicitly scrolling to the final record. Keep the dialog bounds, fixed header, wrapping, and expanded-record assertions. * fix(agent): select model providers without inheriting unrelated auth * fix(webui): prevent resize feedback when toggling agent panel * test(agent): reproduce concurrent comment session races * fix(agent): serialize comment sessions and deduplicate history * docs(changelog): consolidate Pi Durable changes into one entry
219 lines
10 KiB
Plaintext
219 lines
10 KiB
Plaintext
---
|
|
title: Quickstart
|
|
description: Get Shumai up and running using Docker, NPM, or from source.
|
|
---
|
|
|
|
We support three installation options. For most administrators, **Docker Compose** is the fastest and easiest way to deploy Shumai.
|
|
|
|
---
|
|
|
|
## Option 1: Docker Compose (Recommended)
|
|
|
|
Docker Compose is the fastest way to get Shumai running. You do not need to clone the repository or install packages manually. Ensure you have [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) installed, then follow these steps:
|
|
|
|
1. **Create Directory**:
|
|
Create and navigate to a new directory for your configuration and data volumes:
|
|
|
|
```bash
|
|
mkdir shumai && cd shumai
|
|
```
|
|
|
|
2. **Download the Configuration**:
|
|
Download your preferred `docker-compose.yaml` configuration based on your needs and available RAM:
|
|
|
|
- **Lite (Suggested RAM: 2 GB+)**: Minimal deployment containing Shumai and PostgreSQL database.
|
|
|
|
```bash
|
|
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.yaml
|
|
```
|
|
|
|
- **With Embedding Server (Suggested RAM: 4 GB+)**: Adds local multimodal semantic search powered by `shumaiOne/embedding-server` (`EmbeddingGemma 2 740M`).
|
|
|
|
```bash
|
|
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.embedding.yaml
|
|
```
|
|
|
|
- **Full (Suggested RAM: 8 GB+)**: All-in-one setup including `embedding-server`, `turntable-renderer` (3D previews), and `Gotenberg` (document PDF proxying).
|
|
```bash
|
|
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.full.yaml
|
|
```
|
|
|
|
> [!NOTE]
|
|
> By default, the Docker Compose setups use CPU software transcoding. If your server has a GPU (NVIDIA NVENC, Intel QuickSync, AMD/Intel VA-API, or Rockchip RKMPP) and you want to enable GPU hardware acceleration, check the [Hardware Transcoding Guide](/configuration/hardware-transcoding).
|
|
|
|
3. **Configure Environment Variables**:
|
|
Open `docker-compose.yaml` to adjust environment variables for your deployment:
|
|
|
|
- `BETTER_AUTH_URL`: The public base URL of your Shumai server (e.g., `https://shumai.example.com` or `http://12.34.56.78:3000`). It is used for:
|
|
- **Password reset links**: Generates CLI and user password reset URLs (`{BETTER_AUTH_URL}/reset-password?token=...`).
|
|
- **Email notification deep links**: Default base URL for notification emails (if `APP_URL` is unset).
|
|
- **Session cookie security**: Determines whether to issue session cookies with `Secure` flags and `__Secure-` prefixes for HTTPS deployments.
|
|
- **MCP OAuth 2.1 & discovery**: Sets the OAuth resource identifier (`{BETTER_AUTH_URL}/mcp`), discovery endpoints (`/.well-known/...`), and default redirect URI for outbound MCP OAuth.
|
|
|
|
> [!NOTE]
|
|
> **Email/password Web UI login** works over plain HTTP/IP even if `BETTER_AUTH_URL` is omitted. However, setting it is strongly recommended for production, custom domains, or HTTPS deployments. Note that remote deployments must use HTTPS for MCP OAuth 2.1 (RFC 9728); if an HTTP IP address or domain is used, MCP OAuth 2.1 is gracefully disabled while the Web UI and MCP API tokens remain functional.
|
|
|
|
- `BETTER_AUTH_SECRET`: A random secret key used to sign session cookies, JWTs, and presigned file upload/download URLs (in local storage mode). A default placeholder is included in the template for instant local trials, but **you must generate a unique secret for production or public deployments** (e.g., run `openssl rand -base64 32`).
|
|
- `AWS_ENDPOINT_URL_S3`: By default, `AWS_ENDPOINT_URL_S3` is set to `http://localhost:{SHUMAI_SERVER_PORT}`. When you use local storage (the default storage backend with `STORAGE_BACKEND: local`) and expose Shumai on a remote server, custom domain, or custom host/port combination, set `AWS_ENDPOINT_URL_S3` to the external URL that client browsers will use to upload and download files.
|
|
|
|
For example, if you change the port mapping in `docker-compose.yaml` from `3000:3000` to `12345:3000` and deploy on a server with IP address `12.34.56.78`, set:
|
|
|
|
```yaml
|
|
AWS_ENDPOINT_URL_S3: http://12.34.56.78:12345
|
|
```
|
|
|
|
This value must be reachable from client browsers and should include the externally exposed port.
|
|
|
|
- `SHUMAI_SERVER_PORT`: Controls the port the Shumai server listens on. The default is `3000`.
|
|
- **External S3 Storage**: By default, Shumai uses the bundled local storage service in this Docker Compose setup. To use an external S3-compatible storage instead, configure the environment variables for your S3 provider. Here are examples for AWS S3 and Cloudflare R2:
|
|
|
|
**AWS S3 Example:**
|
|
|
|
```yaml
|
|
STORAGE_BACKEND: s3
|
|
S3_BUCKET: your-bucket-name
|
|
S3_ACCESS_KEY_ID: your-access-key-id
|
|
S3_SECRET_ACCESS_KEY: your-secret-access-key
|
|
AWS_ENDPOINT_URL_S3: https://s3.us-east-1.amazonaws.com
|
|
```
|
|
|
|
**Cloudflare R2 Example:**
|
|
|
|
```yaml
|
|
STORAGE_BACKEND: s3
|
|
S3_BUCKET: your-bucket-name
|
|
S3_REGION: auto
|
|
S3_ACCESS_KEY_ID: your-access-key-id
|
|
S3_SECRET_ACCESS_KEY: your-secret-access-key
|
|
AWS_ENDPOINT_URL_S3: https://<account-id>.r2.cloudflarestorage.com
|
|
```
|
|
|
|
4. **Start the Services**:
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
5. **Access the Dashboard**:
|
|
Open your browser and navigate to **`http://localhost:3000`** (or `http://<your-server-ip>:3000` for remote deployments) to access the Shumai Web UI.
|
|
|
|
### Production Deployments (Distributed Workers)
|
|
|
|
If you are deploying Shumai for a production team with high-volume video uploads, we recommend setting up a distributed deployment using dedicated workers and an S3-compatible storage backend. This offloads resource-heavy video transcoding to dedicated worker nodes to keep your main dashboard fast and responsive. For setup instructions, see the [Deploy with Distributed Workers](/configuration/distributed) guide.
|
|
|
|
---
|
|
|
|
## Option 2: Install via NPM
|
|
|
|
You can run Shumai as a global service using the Node Package Manager (NPM).
|
|
|
|
### System Prerequisites
|
|
|
|
To handle media processing and security isolation, the host machine must have the following system utilities installed:
|
|
|
|
- **FFmpeg & FFprobe**: Required for video transcoding and metadata extraction.
|
|
- _macOS_: `brew install ffmpeg`
|
|
- _Linux (Ubuntu/Debian)_: `sudo apt-get install ffmpeg`
|
|
- **dcraw_emu (LibRaw)**: Required for camera RAW image decoding and preview generation.
|
|
- _macOS_: `brew install libraw`
|
|
- _Linux (Ubuntu/Debian)_: `sudo apt-get install libraw-bin`
|
|
- **Agent Sandbox Utilities**: Used to run custom automation scripts securely.
|
|
- _macOS_: `brew install ripgrep`
|
|
- _Linux (Ubuntu/Debian)_: `sudo apt-get install bubblewrap socat ripgrep`
|
|
|
|
### Step-by-Step Setup
|
|
|
|
1. **Start a Database**:
|
|
Shumai requires a PostgreSQL database with the `pgvector` extension. Start a database container:
|
|
```bash
|
|
docker run --name shumai_postgres \
|
|
-e POSTGRES_USER=shumai \
|
|
-e POSTGRES_PASSWORD=shumai_password \
|
|
-e POSTGRES_DB=shumai_db \
|
|
-p 5432:5432 \
|
|
-d pgvector/pgvector:pg18
|
|
```
|
|
2. **Install Shumai**:
|
|
```bash
|
|
npm install -g @shumai-one/shumai
|
|
```
|
|
3. **Configure Environment Variables**:
|
|
Create a new directory, navigate into it, and create a `.env` file:
|
|
|
|
```bash
|
|
mkdir shumai && cd shumai
|
|
```
|
|
|
|
Create a `.env` file with the following variables:
|
|
|
|
```env
|
|
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
|
|
BETTER_AUTH_SECRET=your-random-32-character-secret-key
|
|
BETTER_AUTH_URL=http://localhost:3000
|
|
STORAGE_BACKEND=local
|
|
AWS_ENDPOINT_URL_S3=http://localhost:3000
|
|
```
|
|
|
|
> [!TIP]
|
|
> `BETTER_AUTH_URL` should be set to your public server address for remote or production deployments. `AWS_ENDPOINT_URL_S3` must include the scheme and port (e.g. `http://localhost:3000` or `http://12.34.56.78:3000`) where Shumai is publicly accessible, as client browsers use this URL directly for file uploads.
|
|
|
|
4. **Start Shumai**:
|
|
|
|
> [!IMPORTANT]
|
|
> **For Bun Users:** Since the published package binaries contain a `#!/usr/bin/env node` shebang, running `shumai` directly will execute under Node.js. If you installed using Bun and want to run it under the Bun runtime, prefix the command with `bun run --bun` (e.g., `bun run --bun shumai`).
|
|
|
|
```bash
|
|
shumai
|
|
```
|
|
|
|
Open your browser to `http://localhost:3000`.
|
|
|
|
---
|
|
|
|
## Option 3: Run from Source (For Developers)
|
|
|
|
To set up Shumai locally for development:
|
|
|
|
1. **Clone the Repository and Install Dependencies**:
|
|
```bash
|
|
git clone https://github.com/shumaiOne/shumai.git
|
|
cd shumai
|
|
bun install
|
|
```
|
|
2. **Start a Database**:
|
|
Launch a local database container (as described in the NPM section above):
|
|
```bash
|
|
docker run --name shumai_postgres \
|
|
-e POSTGRES_USER=shumai \
|
|
-e POSTGRES_PASSWORD=shumai_password \
|
|
-e POSTGRES_DB=shumai_db \
|
|
-p 5432:5432 \
|
|
-d pgvector/pgvector:pg18
|
|
```
|
|
3. **Create Environment File**:
|
|
Create a `.env` file at the root of the workspace:
|
|
```env
|
|
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
|
|
BETTER_AUTH_SECRET=ySxs7DxzHDZBbeeHNPEwBuspYwipBqz5Gk5XdBjNhWw=
|
|
BETTER_AUTH_URL=http://localhost:3000
|
|
STORAGE_BACKEND=local
|
|
SHUMAI_SERVER_PORT=3000
|
|
AWS_ENDPOINT_URL_S3=http://localhost:3000
|
|
```
|
|
4. **Generate i18n Translations**:
|
|
```bash
|
|
bun run i18n:compile
|
|
```
|
|
> [!TIP]
|
|
> During frontend development, you can run `bun run i18n:watch` in a separate terminal to automatically recompile translation files whenever you edit strings in `packages/webui/messages/`.
|
|
5. **Run Migrations**:
|
|
Apply database schema migrations:
|
|
```bash
|
|
bun run db:migrate
|
|
```
|
|
6. **Start the Dev Server**:
|
|
```bash
|
|
bun run dev
|
|
```
|
|
This spins up the web server on port `3000` with hot-reloading active.
|