mirror of
https://github.com/shumaiOne/shumai.git
synced 2026-11-22 17:58:23 +00:00
* fix(core): strip trailing slashes when normalizing auth and MCP resource URLs * docs: document BETTER_AUTH_URL in README and quickstart guides * docs: prioritize AWS_ENDPOINT_URL_S3 and clarify applicability to local storage * docs: refine AWS_ENDPOINT_URL_S3 guidance for local storage deployments
141 lines
12 KiB
Plaintext
141 lines
12 KiB
Plaintext
---
|
|
title: Environment Variables
|
|
description: Comprehensive configuration reference for Shumai.
|
|
---
|
|
|
|
Shumai is configured via environment variables. You can define these variables in a `.env` file at the root of your application workspace, or pass them directly to your Docker containers.
|
|
|
|
---
|
|
|
|
## Database Config
|
|
|
|
| Variable | Description | Example / Default |
|
|
| :------------- | :----------------------------------------------------------------------------------------- | :------------------------------------------------------- |
|
|
| `DATABASE_URL` | PostgreSQL connection URL. Must target a database with the `pgvector` extension installed. | `postgresql://user:pass@localhost:5432/db?schema=public` |
|
|
|
|
---
|
|
|
|
## Server Config
|
|
|
|
| Variable | Description | Example / Default |
|
|
| :---------------------- | :------------------------------------------------------------------------------------------------ | :---------------- |
|
|
| `SHUMAI_SERVER_PORT` | The port on which the Shumai web server will listen. | `3000` (default) |
|
|
| `MAX_REQUEST_BODY_SIZE` | Maximum allowed size for request bodies (e.g., for large file uploads). Default is 10GB in bytes. | `10737418240` |
|
|
|
|
---
|
|
|
|
## Authentication & Application Config
|
|
|
|
| Variable | Description | Example / Default |
|
|
| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------- |
|
|
| `BETTER_AUTH_SECRET` | A secure, random 32-byte secret used to sign session cookies and JWTs. | Generate with `openssl rand -base64 32` |
|
|
| `BETTER_AUTH_URL` | The public URL of your Shumai server. Used for MCP OAuth 2.1 discovery, redirect flows, password reset links, and email notifications. | `http://localhost:3000` (respects `SHUMAI_SERVER_PORT` fallback) |
|
|
| `APP_URL` | The public URL of the web application. Used for notification email deep links (falls back to `BETTER_AUTH_URL`). | `https://shumai.example.com` |
|
|
|
|
---
|
|
|
|
## Storage Config
|
|
|
|
Shumai supports storing files locally or on S3-compatible endpoints.
|
|
|
|
| Variable | Description | Example / Default |
|
|
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------ |
|
|
| `STORAGE_BACKEND` | Storage type. Use `local` for local file system storage, or `s3` for S3-compatible cloud storage. | `local` (default) or `s3` |
|
|
| `AWS_ENDPOINT_URL_S3` | Endpoint for S3 storage or local storage. Used by the browser to build file upload URLs. Must include port if deploying remotely or using custom ports. | `http://localhost:3000` (respects `SHUMAI_SERVER_PORT` fallback if unset) |
|
|
| `S3_BUCKET` | S3 bucket name. | `shumai` (default) |
|
|
| `S3_ACCESS_KEY_ID` | Access key credentials for S3. | `minioadmin` (default) |
|
|
| `S3_SECRET_ACCESS_KEY` | Secret key credentials for S3. | `minioadmin` (default) |
|
|
| `S3_REGION` | S3 storage region. | `auto` (default) |
|
|
| `PRESIGNED_URL_EXPIRES_IN` | Number of hours for which generated presigned download/upload links are valid. | `5` (default) |
|
|
|
|
### Local Storage Port Configuration
|
|
|
|
When `STORAGE_BACKEND` is set to `local` (default):
|
|
|
|
- `SHUMAI_SERVER_PORT` configures the port on which the Shumai web server starts and listens.
|
|
- `AWS_ENDPOINT_URL_S3` configures the public/external endpoint used by client browsers to upload and download files. It must include the scheme and port.
|
|
|
|
For example, if you deploy Shumai on a remote server at `http://123.456.7.8` and configure port mapping `12345:3000` (exposing port 3000 internally as port 12345 externally) in Docker Compose:
|
|
|
|
- Set `SHUMAI_SERVER_PORT` to `3000`.
|
|
- Set `AWS_ENDPOINT_URL_S3` to `http://123.456.7.8:12345`.
|
|
|
|
---
|
|
|
|
## Workflow Config
|
|
|
|
Configures background worker execution, concurrency limits, and worker identity for DBOS Transact queues.
|
|
|
|
| Variable | Description | Example / Default |
|
|
| :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------- | :---------------- |
|
|
| `SHUMAI_WORKERS` | Queues listened to by the web server. Options: `all` (default), `none` (API/UI only), `agent` (or `ai`), `transcode`. | `all` (default) |
|
|
| `CONCURRENCY_TRANSCODE` | Maximum concurrent media transcoding tasks executed by workers. | `1` (default) |
|
|
| `CONCURRENCY_AGENT` | Maximum concurrent AI tasks executed by workers. Set to `1` when running local `embedding-server`. | `5` (default) |
|
|
| `SHUMAI_WORKER_ID` | Optional explicit instance ID for worker replicas in multi-node deployments (auto-derived from hostname and process ID if unset). | `worker-1` |
|
|
| `POD_NAME` | Kubernetes pod name, used to provide stable per-pod worker identity across StatefulSet restarts. | `transcode-pod-0` |
|
|
|
|
---
|
|
|
|
## Embedding Config
|
|
|
|
| Variable | Description | Example / Default |
|
|
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------ | :-------------------------------- |
|
|
| `EMBEDDING_PROVIDER` | Multimodal embedding provider. Options: `gemini-embedding-2`, `gemma-embedding-2-openai`. | `gemini-embedding-2` (default) |
|
|
| `GEMMA_EMBEDDING_OPENAI_BASE_URL` | Base URL of the OpenAI-compatible LiteRT-LM embedding server. | `http://embedding-server:9379/v1` |
|
|
| `ENABLE_EMBEDDING_AGENT` | When set to `true`, automatically provisions and enables the system embedding agent for all teams on startup. | `false` (default) |
|
|
| `EMBEDDING_CHUNK_DURATION` | The duration in seconds for each video chunk when generating video embeddings. | `60.0` (default) |
|
|
| `EMBEDDING_CHUNK_OVERLAP` | The duration in seconds to overlap video chunks when generating video embeddings. | `5.0` (default) |
|
|
|
|
## Sandbox Config
|
|
|
|
| Variable | Description | Example / Default |
|
|
| :----------------------------- | :----------------------------------------------------------------------------------------------------- | :---------------- |
|
|
| `ENABLE_WEAKER_NESTED_SANDBOX` | Enables weaker nested sandbox mode for environments without user namespace permissions (e.g., Docker). | `false` (default) |
|
|
|
|
---
|
|
|
|
## Logging Config
|
|
|
|
| Variable | Description | Example / Default |
|
|
| :----------- | :--------------------------------------------------------------------------------------------------- | :---------------- |
|
|
| `LOG_LEVEL` | Pino logging level. Options: `debug`, `info`, `warn`, `error`. | `info` (default) |
|
|
| `LOG_FORMAT` | Log format style. Use `json` for production logging, or `pretty` for human-readable terminal output. | `json` (default) |
|
|
|
|
---
|
|
|
|
## LLM API Key
|
|
|
|
API keys to AI providers on startup.
|
|
|
|
| Variable | Description | Example / Default |
|
|
| :------------------ | :---------------------------------- | :---------------- |
|
|
| `GEMINI_API_KEY` | API key for Google Gemini provider. | `AIzaSy...` |
|
|
| `OPENAI_API_KEY` | API key for OpenAI provider. | `sk-proj-...` |
|
|
| `ANTHROPIC_API_KEY` | API key for Anthropic provider. | `sk-ant-...` |
|
|
|
|
---
|
|
|
|
## External Integrations Config
|
|
|
|
Environment variables can configure external microservices globally. When set, these environment variables take precedence over any team-level settings configured in **Team Settings → Integrations**, and lock the corresponding settings fields in the WebUI to read-only.
|
|
|
|
### Gotenberg Document Converter
|
|
|
|
Used to convert Office documents, HTML, Markdown, and CSV files into high-fidelity PDF proxies for in-browser previewing. See the [Gotenberg Guide](/using-shumai/gotenberg) for setup instructions.
|
|
|
|
| Variable | Description | Example / Default |
|
|
| :------------------------------ | :----------------------------------------------------------------------- | :---------------------- |
|
|
| `GOTENBERG_URL` | Base URL of the external Gotenberg conversion API. | `http://gotenberg:3000` |
|
|
| `GOTENBERG_BASIC_AUTH_USERNAME` | Username when Basic Authentication is enabled on the Gotenberg instance. | `admin` |
|
|
| `GOTENBERG_BASIC_AUTH_PASSWORD` | Password when Basic Authentication is enabled on the Gotenberg instance. | `secret` |
|
|
|
|
### 3D Turntable Renderer
|
|
|
|
Used to convert 3D model files (GLB, OBJ, FBX, USD, STL, DAE) into interactive 360° turntable video proxies, posters, and hover sprites. See the [3D Asset Support Guide](/using-shumai/3d-asset-support) for setup instructions.
|
|
|
|
| Variable | Description | Example / Default |
|
|
| :--------------------------------------- | :-------------------------------------------------------------------------------------------------------------- | :------------------------------- |
|
|
| `TURNTABLE_RENDERER_URL` | Base URL of the external turntable-renderer service. | `http://turntable-renderer:3000` |
|
|
| `TURNTABLE_RENDERER_BASIC_AUTH_USERNAME` | Username when Basic Authentication is enabled on the turntable renderer (alias: `TURNTABLE_RENDERER_USERNAME`). | `admin` |
|
|
| `TURNTABLE_RENDERER_BASIC_AUTH_PASSWORD` | Password when Basic Authentication is enabled on the turntable renderer (alias: `TURNTABLE_RENDERER_PASSWORD`). | `secret` |
|