Files
shumai/docs/configuration/env-variables.mdx
T
Yiling-J 687b5a79d8 fix(core): strip trailing slashes when normalizing auth and MCP resource URLs (#506)
* 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
2026-10-29 17:24:31 +08:00

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` |