2026-06-16 12:15:53 +08:00
---
title: Quickstart
2026-06-16 14:44:42 +08:00
description: Get Shumai up and running using Docker, NPM, or from source.
2026-06-16 12:15:53 +08:00
---
2026-06-16 14:44:42 +08:00
We support three installation options. For most administrators, **Docker Compose** is the fastest and easiest way to deploy Shumai.
2026-06-16 12:15:53 +08:00
---
## Option 1: Docker Compose (Recommended)
2026-06-16 14:44:42 +08:00
Docker Compose automatically configures and spins up all required services (the web application, a database, and local storage).
2026-06-16 12:15:53 +08:00
2026-06-16 14:44:42 +08:00
1. **Download the Configuration**:
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.yaml
```
2. **Start the Services**:
```bash
docker compose up -d
```
3. **Access the Dashboard**:
Open your browser and navigate to **`http://localhost:3000`** to access the Shumai Web UI.
2026-06-16 12:15:53 +08:00
2026-06-16 14:53:03 +08:00
### 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.
2026-06-16 12:15:53 +08:00
---
2026-06-16 14:44:42 +08:00
## Option 2: Install via NPM
2026-06-16 12:15:53 +08:00
2026-06-16 14:44:42 +08:00
You can run Shumai as a global service using the Node Package Manager (NPM).
2026-06-16 12:15:53 +08:00
2026-06-16 14:44:42 +08:00
### System Prerequisites
2026-06-16 12:15:53 +08:00
2026-06-16 14:44:42 +08:00
To handle media processing and security isolation, the host machine must have the following system utilities installed:
2026-06-16 12:15:53 +08:00
2026-06-16 14:44:42 +08:00
- **FFmpeg & FFprobe**: Required for video transcoding and metadata extraction.
- _macOS_: `brew install ffmpeg`
- _Linux (Ubuntu/Debian)_: `sudo apt-get install ffmpeg`
- **Agent Sandbox Utilities**: Used to run custom automation scripts securely.
- _macOS_: `brew install ripgrep`
- _Linux (Ubuntu/Debian)_: `sudo apt-get install bubblewrap socat ripgrep`
2026-06-16 12:15:53 +08:00
2026-06-16 14:44:42 +08:00
### Step-by-Step Setup
1. **Start a Database**:
Shumai requires a PostgreSQL database with the `pgvector` extension. Start a database container:
2026-06-16 12:15:53 +08:00
```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
```
2026-06-16 14:44:42 +08:00
2. **Install Shumai**:
2026-06-16 12:15:53 +08:00
```bash
npm install -g @shumai-one/shumai
```
3. **Configure Environment Variables**:
2026-06-16 14:44:42 +08:00
Create a new directory, navigate into it, and create a `.env` file:
2026-06-16 12:15:53 +08:00
```bash
mkdir shumai && cd shumai
```
2026-06-16 14:44:42 +08:00
Create a `.env` file with the following variables:
2026-06-16 12:15:53 +08:00
```env
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
2026-06-16 14:44:42 +08:00
BETTER_AUTH_SECRET=your-random-32-character-secret-key
2026-06-16 12:15:53 +08:00
STORAGE_BACKEND=local
2026-06-18 10:22:16 +08:00
AWS_ENDPOINT_URL_S3=http://localhost
2026-06-16 12:15:53 +08:00
```
2026-06-16 14:44:42 +08:00
4. **Start Shumai**:
2026-06-16 12:15:53 +08:00
```bash
shumai
```
2026-06-16 14:44:42 +08:00
Open your browser to `http://localhost:3000`.
2026-06-16 12:15:53 +08:00
---
## Option 3: Run from Source (For Developers)
2026-06-16 14:44:42 +08:00
If you wish to run Shumai locally to customize the platform or contribute:
2026-06-16 12:15:53 +08:00
2026-06-16 14:44:42 +08:00
1. **Clone the Repository**:
2026-06-16 12:15:53 +08:00
```bash
git clone https://github.com/shumaiOne/shumai.git
cd shumai
2026-06-16 14:44:42 +08:00
```
2. **Install Dependencies**:
```bash
2026-06-16 12:15:53 +08:00
bun install
```
2026-06-16 14:44:42 +08:00
3. **Start a Database**:
Launch a local database container (as described in the NPM section above).
4. **Run Migrations**:
Set up your `.env` file at the root, then apply database migrations:
2026-06-16 12:15:53 +08:00
```bash
bun run db:migrate
```
2026-06-16 14:44:42 +08:00
5. **Start the Dev Server**:
2026-06-16 12:15:53 +08:00
```bash
bun run dev
```
2026-06-16 14:44:42 +08:00
This spins up the web server on port `3000` with hot-reloading active.