Environment Variables
Complete reference for all environment variables in TMA Cloud.
Complete reference for all environment variables in TMA Cloud.
Application Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
NODE_ENV | No | development | Environment mode |
BPORT | No | 3000 | Backend server port |
BACKEND_URL | Yes (OnlyOffice) | - | Public backend URL |
Reverse proxy trust is configured in Settings → Administration → Known Proxies, not through an environment variable. See Known Proxies.
Database Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
DB_HOST | No | localhost | PostgreSQL host |
DB_PORT | No | 5432 | PostgreSQL port |
DB_USER | No | postgres | Database username |
DB_PASSWORD | Yes | - | Database password |
DB_NAME | No | tma_cloud_storage | Database name |
DB_SSLMODE | No | disable | SSL mode (require for TLS) |
PGBOSS_SCHEMA | No | pgboss | pg-boss job queue schema |
DB_CONTAINER | No | auto-detected | Docker container name for backup/restore script |
BACKUP_RETAIN_COUNT | No | 10 | Number of database backups to keep before pruning |
Redis Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
REDIS_HOST | No | localhost | Redis host |
REDIS_PORT | No | 6379 | Redis port |
REDIS_PASSWORD | No | - | Redis password (recommended) |
REDIS_DB | No | 0 | Redis database number |
Note: Redis is optional. App works without it but caching is disabled.
Authentication
| Variable | Required | Default | Description |
|---|---|---|---|
JWT_SECRET | Yes | - | Secret key for JWT tokens |
FORCE_INSECURE_COOKIES | No | false | If true, auth cookie has no Secure flag in production |
SESSION_IDLE_DAYS | No | 30 | Days of inactivity before a session ends |
SESSION_IDLE_DAYS: Tokens are issued for this window and re-issued while the user is active, so an active user is not logged out mid-use. A session ends after this many days with no requests. Values below 1 are ignored and fall back to 30. See Authentication.
Google OAuth (Optional)
| Variable | Required | Description |
|---|---|---|
GOOGLE_CLIENT_ID | No | Google OAuth Client ID |
GOOGLE_CLIENT_SECRET | No | Google OAuth Client Secret |
GOOGLE_REDIRECT_URI | No | Redirect URI (must match Google Console) |
Note: All three must be set to enable Google OAuth.
File Storage
| Variable | Required | Default | Description |
|---|---|---|---|
FILE_ENCRYPTION_KEY | Yes (production) | Development default | Key-encryption key (KEK) for files |
FILE_KEK_VERSION | No | 1 | Version of the current KEK |
Note: File contents use bounded streaming. The multipart uploader buffers at most four parts per active upload. Per-file size is controlled by the max upload size setting in Settings → Storage.
Key rotation: To rotate, set a new FILE_ENCRYPTION_KEY, increment FILE_KEK_VERSION, and keep the previous key as FILE_ENCRYPTION_KEY_V<oldVersion> (e.g. FILE_ENCRYPTION_KEY_V1) until rotate-kek.js reports Remaining=0. See CLI Commands.
S3-compatible
A bucket is required. The backend stops at startup if its endpoint, bucket name, access key, or secret key is missing.
Supported: Cloudflare R2 (R2*), RustFS / other S3 (RUSTFS*), AWS S3 (AWS_). Use one set of vars.
Cloudflare R2
| Setting | Required | Default | Env var |
|---|---|---|---|
| Account ID | Yes* | - | R2_ACCOUNT_ID |
| Bucket | Yes* | - | R2_BUCKET |
| Access key | Yes* | - | R2_ACCESS_KEY_ID |
| Secret key | Yes* | - | R2_SECRET_ACCESS_KEY |
| Endpoint | No | derived | R2_ENDPOINT (optional) |
| Public URL | No | - | R2_PUBLIC_URL (optional) |
R2_ACCESS_KEY and R2_SECRET_KEY are accepted as fallbacks for the two key variables, but R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY take precedence when both are set.
*Required when using R2. Endpoint is https://<R2_ACCOUNT_ID>.r2.cloudflarestorage.com unless R2_ENDPOINT is set. Region is set to auto for R2.
Other S3-compatible (RustFS, AWS, etc.)
| Setting | Required | Default | Env var (either name) |
|---|---|---|---|
| Endpoint | Yes* | - | RUSTFS_ENDPOINT or AWS_S3_ENDPOINT |
| Bucket | Yes* | - | RUSTFS_BUCKET or AWS_S3_BUCKET |
| Access key | Yes* | - | RUSTFS_ACCESS_KEY or AWS_ACCESS_KEY_ID |
| Secret key | Yes* | - | RUSTFS_SECRET_KEY or AWS_SECRET_ACCESS_KEY |
| Region | No | us-east-1 | RUSTFS_REGION or AWS_REGION |
| Path style | No | true | RUSTFS_FORCE_PATH_STYLE (set false to disable) |
*Required when not using R2. Use one set of names consistently.
Note: From backend, npm run s3:protect-all applies bucket protections (public access block, HTTPS-only policy, versioning, optional encryption, lifecycle). Lifecycle aborts incomplete multipart after 1 day and deletes noncurrent versions after 7 days. Review orphans periodically from Settings → Administration; see Orphan Review.
OnlyOffice Background Save
| Variable | Required | Default | Description |
|---|---|---|---|
ONLYOFFICE_AUTOSAVE_INTERVAL_MS | No | 300000 | Interval for worker force-save schedules |
ONLYOFFICE_REJECT_UNAUTHORIZED | No | true | Set to false for a self-signed OnlyOffice cert |
ONLYOFFICE_AUTOSAVE_INTERVAL_MS is optional. Do not set it when the five-minute default is suitable. Valid overrides are 1-60 whole minutes that divide evenly into an hour; invalid values use five minutes. The standalone worker must be running for scheduled force-save commands.
Keep ONLYOFFICE_REJECT_UNAUTHORIZED enabled unless the document server uses a self-signed certificate on a trusted network.
Desktop Development
| Variable | Required | Default | Description |
|---|---|---|---|
TMA_CLOUDFS_EXE | No | Build output path | Cloud Drive host executable override |
TMA_CLOUD_CLIPBOARD_DEBUG | No | 0 | Set to 1 to log desktop clipboard diagnostics |
These variables affect the Electron client and are not server settings. Clipboard diagnostics can contain local file paths; disable them outside development.
Logging Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
LOG_LEVEL | No | info | Log level (fatal, error, warn, info, debug, trace) |
LOG_FORMAT | No | json (prod), pretty (dev) | Log format (json, pretty) |
METRICS_ALLOWED_IPS | No | 127.0.0.1,::ffff:127.0.0.1,::1 | Comma-separated IPs allowed to access /metrics |
QUEUE_METRICS_INTERVAL_SECONDS | No | 60 | Audit queue gauge refresh interval (minimum 10) |
Audit Logging Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
AUDIT_WORKER_CONCURRENCY | No | 5 | Audit batch size and worker concurrency cap |
AUDIT_JOB_TTL_SECONDS | No | 82800 (23h) | Job TTL (must be < 24h) |
Last Access Time
| Variable | Required | Default | Description |
|---|---|---|---|
ACCESS_TIME_TRACKING | No | 1 | Set to 0 or false to stop recording access times |
ACCESS_TIME_WINDOW_MINUTES | No | 60 | How stale a stored value must be before it is rewritten |
ACCESS_TIME_FLUSH_SECONDS | No | 10 | How long updates are buffered before being written |
ACCESS_TIME_WINDOW_MINUTES: Repeat reads of the same item inside this window are not written down at all. The default of 60 matches the one-hour accuracy NTFS guarantees for its last-access time. Lower it for finer timestamps at the cost of more writes, or set it to 0 to record every read.
ACCESS_TIME_FLUSH_SECONDS: Updates are held in memory and written in one batched statement per interval, so a download never waits on the write. Raising it reduces the number of statements; lowering it makes timestamps appear sooner. Buffered updates are flushed on shutdown.
ACCESS_TIME_TRACKING: Turning it off leaves existing accessed_at values in place but stops updating them. Windows offers the same switch as NtfsDisableLastAccessUpdate. See File System.
Related Topics
- Environment Setup - Setup guide
- Docker Compose / Docker - Docker Compose and env configuration