mirror of
https://github.com/shumaiOne/shumai.git
synced 2026-11-22 11:07:18 +00:00
* feat(storage): add team auto-archive assets policy and background job * fix(storage): address code review feedback on lock safety, starvation, and permissions * docs: update readme and expand archive storage documentation with auto-archive details * feat(storage): log info message on auto-archive job start and finish with archived count * style(storage): stack age threshold and grace period vertically with updated grace period description * fix(storage): only log auto-archive info messages when candidate assets are found to process
162 lines
17 KiB
Plaintext
162 lines
17 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 links are valid. | `5` (default) |
|
|
| `PRESIGNED_UPLOAD_URL_EXPIRES_IN` | Number of hours for which generated presigned upload links are valid. Falls back to `PRESIGNED_URL_EXPIRES_IN` if unset. | `12` (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`.
|
|
|
|
### Archive Storage Config
|
|
|
|
Shumai supports configuring an optional **Archive Storage** tier (`local` NAS/directory or `s3` bucket/storage class) for moving original raw files while keeping proxies, previews, thumbnails, and metadata in main storage.
|
|
|
|
| Variable | Description | Example / Default |
|
|
| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------- |
|
|
| `ARCHIVE_STORAGE_BACKEND` | Archive storage type. Leave unset to disable archive storage, or set to `local` or `s3`. | Unset (disabled), `local`, or `s3` |
|
|
| `ARCHIVE_LOCAL_ROOT` | Required when `ARCHIVE_STORAGE_BACKEND=local`. Root directory (e.g., a mounted NAS folder) where archived original files are stored directly under `<ARCHIVE_LOCAL_ROOT>/<key>`. | `/mnt/nas/shumai-archive` |
|
|
| `ARCHIVE_AWS_ENDPOINT_URL_S3` | Optional custom S3 endpoint for archive storage when `ARCHIVE_STORAGE_BACKEND=s3` (independent of `AWS_ENDPOINT_URL_S3`). | `https://s3.us-east-1.amazonaws.com` |
|
|
| `ARCHIVE_S3_BUCKET` | Required when `ARCHIVE_STORAGE_BACKEND=s3`. Target S3 bucket for archived files (can be a dedicated bucket or the same bucket as `S3_BUCKET` with a cold storage class). | `shumai-archive` |
|
|
| `ARCHIVE_S3_ACCESS_KEY_ID` | Required when `ARCHIVE_STORAGE_BACKEND=s3`. S3 access key ID for archive storage. | `AKIA...` |
|
|
| `ARCHIVE_S3_SECRET_ACCESS_KEY` | Required when `ARCHIVE_STORAGE_BACKEND=s3`. S3 secret access key for archive storage. | `...` |
|
|
| `ARCHIVE_S3_REGION` | S3 region for archive storage when `ARCHIVE_STORAGE_BACKEND=s3`. | `auto` (default) |
|
|
| `ARCHIVE_S3_STORAGE_CLASS` | Optional S3 `StorageClass` header applied when archiving objects (accepts any standard or provider-specific class string; required and must not be `STANDARD` for same-bucket tiering). | `GLACIER_IR`, `GLACIER`, `DEEP_ARCHIVE`, `STANDARD_IA` |
|
|
| `ARCHIVE_S3_USE_RESTORE_OBJECT` | Controls whether S3 `RestoreObject` is called before reading archived objects (`auto`, `true`, or `false`). | `auto` (default) |
|
|
| `ARCHIVE_S3_RESTORE_DAYS` | Number of days a restored copy of a cold S3 object remains readable during restoration. | `1` (default) |
|
|
| `ARCHIVE_S3_RESTORE_TIER` | Optional S3 Glacier retrieval tier (`Expedited`, `Standard`, `Bulk`). Omitted when unset for S3-compatible providers that reject `GlacierJobParameters`. | Unset (default) |
|
|
| `AUTO_ARCHIVE_INTERVAL_MINUTES` | Frequency (in minutes) of the background auto-archive scanner job. Accepts decimal values (e.g. `0.02` for testing). | `60` (1 hour default) |
|
|
|
|
---
|
|
|
|
## 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`, `archive`. | `all` (default) |
|
|
| `CONCURRENCY_TRANSCODE` | Maximum concurrent media transcoding tasks executed by workers. | `1` (default) |
|
|
| `CONCURRENCY_ARCHIVE` | Maximum concurrent archive and restore tasks executed by workers. | `5` (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` |
|