mirror of
https://github.com/shumaiOne/shumai.git
synced 2026-11-19 14:16:29 +00:00
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 and AI agents to separate, 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.
|