cjw/Oxicloud
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

doc: update example.env and docs/config/env.md

Browse Source
This commit is contained in:
Edouard Vanbelle
2026-05-10 22:12:55 +02:00
parent ad711e18ea
commit 8b08ee165d
2 changed files with 268 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/config/env.md
+117 -17
View File
@@ -10,7 +10,8 @@ Most runtime variables use the `OXICLOUD_` prefix. A few build-time or allocator
| `OXICLOUD_STATIC_PATH` | `./static` | Static files directory |
| `OXICLOUD_SERVER_PORT` | `8086` | Server port |
| `OXICLOUD_SERVER_HOST` | `127.0.0.1` | Server bind address |
| `OXICLOUD_BASE_URL` | (auto) | Public base URL for share links |
| `OXICLOUD_BASE_URL` | (auto) | Public base URL for share links; defaults to `http://{host}:{port}` |
| `OXICLOUD_MAX_UPLOAD_SIZE` | `10737418240` | Maximum upload size in bytes (10 GB on 64-bit, 1 GB on 32-bit) |
## Database
@@ -32,9 +33,25 @@ Most runtime variables use the `OXICLOUD_` prefix. A few build-time or allocator
| Variable | Default | Description |
|---|---|---|
| `OXICLOUD_JWT_SECRET` | (random) | JWT signing secret |
| `OXICLOUD_ACCESS_TOKEN_EXPIRY_SECS` | `3600` | Access token lifetime (seconds) |
| `OXICLOUD_REFRESH_TOKEN_EXPIRY_SECS` | `2592000` | Refresh token lifetime (seconds) |
| `OXICLOUD_JWT_SECRET` | (auto-generated) | JWT signing secret; auto-persisted to `<STORAGE_PATH>/.jwt_secret` if unset |
| `OXICLOUD_ACCESS_TOKEN_EXPIRY_SECS` | `3600` | Access token lifetime (1 hour) |
| `OXICLOUD_REFRESH_TOKEN_EXPIRY_SECS` | `604800` | Refresh token lifetime (7 days); active sessions auto-renew on use |
| `OXICLOUD_HASH_MEMORY_COST` | `65536` | Argon2id memory cost in KiB (64 MiB) |
| `OXICLOUD_HASH_TIME_COST` | `3` | Argon2id iteration count |
| `OXICLOUD_HASH_PARALLELISM` | `2` | Argon2id parallelism lanes |
### Rate Limiting & Account Lockout
| Variable | Default | Description |
|---|---|---|
| `OXICLOUD_RATE_LIMIT_LOGIN_MAX` | `10` | Max login attempts per IP per window |
| `OXICLOUD_RATE_LIMIT_LOGIN_WINDOW_SECS` | `60` | Login rate-limit window (seconds) |
| `OXICLOUD_RATE_LIMIT_REGISTER_MAX` | `5` | Max registration attempts per IP per window |
| `OXICLOUD_RATE_LIMIT_REGISTER_WINDOW_SECS` | `3600` | Registration rate-limit window (seconds) |
| `OXICLOUD_RATE_LIMIT_REFRESH_MAX` | `20` | Max token refresh attempts per IP per window |
| `OXICLOUD_RATE_LIMIT_REFRESH_WINDOW_SECS` | `60` | Refresh rate-limit window (seconds) |
| `OXICLOUD_LOCKOUT_MAX_FAILURES` | `5` | Consecutive failed logins before account lockout |
| `OXICLOUD_LOCKOUT_DURATION_SECS` | `900` | Account lockout duration (15 minutes) |
## Feature Flags
@@ -44,7 +61,70 @@ Most runtime variables use the `OXICLOUD_` prefix. A few build-time or allocator
| `OXICLOUD_ENABLE_USER_STORAGE_QUOTAS` | `false` | Per-user storage quotas |
| `OXICLOUD_ENABLE_FILE_SHARING` | `true` | File/folder sharing |
| `OXICLOUD_ENABLE_TRASH` | `true` | Trash / recycle bin |
| `OXICLOUD_ENABLE_SEARCH` | `true` | Search |
| `OXICLOUD_ENABLE_SEARCH` | `true` | Full-text and metadata search |
| `OXICLOUD_ENABLE_MUSIC` | `true` | Music playlists and audio metadata |
| `OXICLOUD_EXPOSE_SYSTEM_USERS` | `true` | Expose other OxiCloud users as a read-only address book at `GET /api/address-books` |
## Storage Backend
| Variable | Default | Description |
|---|---|---|
| `OXICLOUD_STORAGE_BACKEND` | `local` | Blob storage backend: `local`, `s3`, or `azure` |
### S3-Compatible (AWS S3, Backblaze B2, Cloudflare R2, MinIO)
Used when `OXICLOUD_STORAGE_BACKEND=s3`.
| Variable | Default | Description |
|---|---|---|
| `OXICLOUD_S3_BUCKET` | — | S3 bucket name (required) |
| `OXICLOUD_S3_REGION` | `us-east-1` | AWS region |
| `OXICLOUD_S3_ACCESS_KEY` | — | Access key ID |
| `OXICLOUD_S3_SECRET_KEY` | — | Secret access key |
| `OXICLOUD_S3_ENDPOINT_URL` | — | Custom endpoint for non-AWS providers (e.g. `https://s3.example.com`) |
| `OXICLOUD_S3_FORCE_PATH_STYLE` | `false` | Force path-style URLs (required for MinIO, R2) |
### Azure Blob Storage
Used when `OXICLOUD_STORAGE_BACKEND=azure`.
| Variable | Default | Description |
|---|---|---|
| `OXICLOUD_AZURE_ACCOUNT_NAME` | — | Storage account name (required) |
| `OXICLOUD_AZURE_ACCOUNT_KEY` | — | Storage account key |
| `OXICLOUD_AZURE_CONTAINER` | — | Blob container name (required) |
| `OXICLOUD_AZURE_SAS_TOKEN` | — | SAS token (alternative to account key) |
### Local Disk Cache for Remote Backends
A least-recently-used disk cache that can speed up repeated reads from S3 or Azure.
| Variable | Default | Description |
|---|---|---|
| `OXICLOUD_STORAGE_CACHE_ENABLED` | `false` | Enable LRU disk cache |
| `OXICLOUD_STORAGE_CACHE_MAX_SIZE` | `53687091200` | Max cache size in bytes (50 GB) |
| `OXICLOUD_STORAGE_CACHE_PATH` | `{STORAGE_PATH}/.blob-cache` | Cache directory |
### Client-Side Encryption
AES-256-GCM encryption applied to blobs before they are written to any backend.
| Variable | Default | Description |
|---|---|---|
| `OXICLOUD_STORAGE_ENCRYPTION_ENABLED` | `false` | Enable at-rest blob encryption |
| `OXICLOUD_STORAGE_ENCRYPTION_KEY` | — | Base64-encoded 32-byte encryption key; generate with `openssl rand -base64 32` |
### Retry Policy (Remote Backends)
Exponential backoff retries for transient errors on S3 and Azure.
| Variable | Default | Description |
|---|---|---|
| `OXICLOUD_STORAGE_RETRY_ENABLED` | `true` | Enable retry with exponential backoff |
| `OXICLOUD_STORAGE_RETRY_MAX_RETRIES` | `3` | Maximum retry attempts |
| `OXICLOUD_STORAGE_RETRY_INITIAL_BACKOFF_MS` | `100` | Initial backoff in milliseconds |
| `OXICLOUD_STORAGE_RETRY_MAX_BACKOFF_MS` | `10000` | Maximum backoff cap in milliseconds |
| `OXICLOUD_STORAGE_RETRY_BACKOFF_MULTIPLIER` | `2.0` | Backoff multiplier per retry |
## OIDC / SSO
@@ -56,13 +136,13 @@ See the [OIDC configuration guide](/config/oidc) for details.
| `OXICLOUD_OIDC_ISSUER_URL` | — | OIDC issuer URL |
| `OXICLOUD_OIDC_CLIENT_ID` | — | Client ID |
| `OXICLOUD_OIDC_CLIENT_SECRET` | — | Client secret |
| `OXICLOUD_OIDC_REDIRECT_URI` | `http://localhost:8086/api/auth/oidc/callback` | Callback URL |
| `OXICLOUD_OIDC_REDIRECT_URI` | `http://localhost:8086/api/auth/oidc/callback` | Callback URL (must match IdP config) |
| `OXICLOUD_OIDC_SCOPES` | `openid profile email` | Requested scopes |
| `OXICLOUD_OIDC_FRONTEND_URL` | `http://localhost:8086` | Frontend URL |
| `OXICLOUD_OIDC_AUTO_PROVISION` | `true` | Auto-create users on first SSO login |
| `OXICLOUD_OIDC_ADMIN_GROUPS` | — | Groups that grant admin role |
| `OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN` | `false` | Hide password form when OIDC enabled |
| `OXICLOUD_OIDC_PROVIDER_NAME` | `SSO` | Display name for the provider |
| `OXICLOUD_OIDC_FRONTEND_URL` | `http://localhost:8086` | Frontend URL to redirect to after login |
| `OXICLOUD_OIDC_AUTO_PROVISION` | `true` | Auto-create users on first SSO login (JIT provisioning) |
| `OXICLOUD_OIDC_ADMIN_GROUPS` | — | Comma-separated OIDC groups that grant admin role |
| `OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN` | `false` | Hide password form when OIDC is active |
| `OXICLOUD_OIDC_PROVIDER_NAME` | `SSO` | Display name for the provider shown in UI |
## WOPI (Office Editing)
@@ -73,21 +153,40 @@ See the [WOPI configuration guide](/config/wopi) for details.
| `OXICLOUD_WOPI_ENABLED` | `false` | Enable WOPI |
| `OXICLOUD_WOPI_DISCOVERY_URL` | — | Collabora/OnlyOffice discovery URL |
| `OXICLOUD_WOPI_BASE_URL` | `OXICLOUD_BASE_URL` | URL the editor uses to call OxiCloud's `/wopi/*` endpoints |
| `OXICLOUD_WOPI_PUBLIC_BASE_URL` | `OXICLOUD_WOPI_BASE_URL` | URL the browser uses to open OxiCloud's WOPI host page and `postMessage` origin |
| `OXICLOUD_WOPI_PUBLIC_BASE_URL` | `OXICLOUD_WOPI_BASE_URL` | URL the browser uses to open OxiCloud's WOPI host page |
| `OXICLOUD_WOPI_SECRET` | (JWT secret) | WOPI token signing key |
| `OXICLOUD_WOPI_TOKEN_TTL_SECS` | `86400` | Token lifetime |
| `OXICLOUD_WOPI_LOCK_TTL_SECS` | `1800` | Lock expiration |
| `OXICLOUD_WOPI_TOKEN_TTL_SECS` | `86400` | Token lifetime (24 hours) |
| `OXICLOUD_WOPI_LOCK_TTL_SECS` | `1800` | Lock expiration (30 minutes) |
When Collabora or OnlyOffice runs on a different hostname, set `OXICLOUD_WOPI_PUBLIC_BASE_URL` to the public OxiCloud URL that the browser can reach. If the editor reaches OxiCloud through a different internal URL, also set `OXICLOUD_WOPI_BASE_URL` for those callbacks.
## Nextcloud Compatibility
Enables the Nextcloud-compatible API layer (`/remote.php/`, `/ocs/`, `/status.php`, Login Flow v2) for clients that use the Nextcloud protocol.
| Variable | Default | Description |
|---|---|---|
| `OXICLOUD_NEXTCLOUD_ENABLED` | `false` | Enable Nextcloud compatibility layer |
| `OXICLOUD_NEXTCLOUD_INSTANCE_ID` | `ocnca` | Instance ID suffix used in `oc:id` formatting |
| `OXICLOUD_NEXTCLOUD_VERSION` | `28.0.4` | Emulated Nextcloud version reported to clients (format: `major.minor.patch`) |
## Trusted Proxy
| Variable | Default | Description |
|---|---|---|
| `OXICLOUD_TRUST_PROXY_CIDR` | — | Comma-separated list of trusted proxy CIDRs; enables `X-Forwarded-For` / `X-Real-IP` extraction for those source IPs |
| `OXICLOUD_TRUST_PROXY_HEADERS` | — | **Deprecated.** Use `OXICLOUD_TRUST_PROXY_CIDR` instead |
Example: `OXICLOUD_TRUST_PROXY_CIDR=127.0.0.1/32,10.0.0.0/8,172.16.0.0/12`
## Allocator Tuning
These variables are read directly by **mimalloc**, not by OxiCloud's config parser.
| Variable | Default | Description |
|---|---|---|
| `MIMALLOC_PURGE_DELAY` | `0` | Delay in ms before freed memory is returned to the OS |
| `MIMALLOC_ALLOW_LARGE_OS_PAGES` | `0` | Enable or disable large OS pages for allocations |
| `MIMALLOC_PURGE_DELAY` | `0` | Delay in ms before freed memory is returned to the OS (`0` = immediately, recommended for Docker) |
| `MIMALLOC_ALLOW_LARGE_OS_PAGES` | `0` | Enable 2 MiB huge pages (`0` = off, recommended for Docker to avoid THP RSS inflation) |
## Internal Defaults (not configurable via env)
@@ -100,5 +199,6 @@ These variables are read directly by **mimalloc**, not by OxiCloud's config pars
| Streaming chunk size | 1 MB |
| Max parallel chunks | 8 |
| Trash retention | 30 days |
| Argon2id memory cost | 64 MB |
| Argon2id memory cost | 64 MiB |
| Argon2id time cost | 3 iterations |
| Nextcloud Login Flow v2 TTL | 600 s |
example.env
+151 -17
View File
@@ -30,6 +30,9 @@ OXICLOUD_SERVER_HOST=127.0.0.1
# Example: https://cloud.example.com
#OXICLOUD_BASE_URL=https://cloud.example.com
# Maximum upload size in bytes (default: 10 GB on 64-bit)
#OXICLOUD_MAX_UPLOAD_SIZE=10737418240
# -----------------------------------------------------------------------------
# DATABASE CONFIGURATION
# -----------------------------------------------------------------------------
@@ -48,8 +51,7 @@ OXICLOUD_DB_CONNECTION_STRING=postgres://postgres:postgres@postgres/oxicloud
# Maximum connections for the maintenance pool (background/batch tasks).
# This pool is isolated from user requests, preventing background operations
# (verify_integrity, garbage_collect, storage recalculation) from starving
# interactive traffic. Default: 5
# from starving interactive traffic. Default: 5
#OXICLOUD_DB_MAINTENANCE_MAX_CONNECTIONS=5
# Minimum connections for the maintenance pool. Default: 1
@@ -74,8 +76,43 @@ DATABASE_URL=postgres://postgres:postgres@localhost:5432/oxicloud
# Access token lifetime in seconds (default: 3600 = 1 hour)
#OXICLOUD_ACCESS_TOKEN_EXPIRY_SECS=3600
# Refresh token lifetime in seconds (default: 2592000 = 30 days)
#OXICLOUD_REFRESH_TOKEN_EXPIRY_SECS=2592000
# Refresh token lifetime in seconds (default: 604800 = 7 days)
# Active sessions auto-renew on use via token rotation, so users stay logged in
# as long as they interact within this window.
#OXICLOUD_REFRESH_TOKEN_EXPIRY_SECS=604800
# Argon2id password hashing parameters
# Increase memory cost for stronger hashing at the expense of login latency.
# Memory cost is in KiB (default: 65536 = 64 MiB)
#OXICLOUD_HASH_MEMORY_COST=65536
# Number of iterations (default: 3)
#OXICLOUD_HASH_TIME_COST=3
# Parallelism lanes (default: 2)
#OXICLOUD_HASH_PARALLELISM=2
# -----------------------------------------------------------------------------
# RATE LIMITING & ACCOUNT LOCKOUT
# -----------------------------------------------------------------------------
# Max login attempts per IP before rate-limiting kicks in (default: 10)
#OXICLOUD_RATE_LIMIT_LOGIN_MAX=10
# Rate-limit window for logins in seconds (default: 60)
#OXICLOUD_RATE_LIMIT_LOGIN_WINDOW_SECS=60
# Max registration attempts per IP per window (default: 5)
#OXICLOUD_RATE_LIMIT_REGISTER_MAX=5
# Rate-limit window for registrations in seconds (default: 3600)
#OXICLOUD_RATE_LIMIT_REGISTER_WINDOW_SECS=3600
# Max token refresh attempts per IP per window (default: 20)
#OXICLOUD_RATE_LIMIT_REFRESH_MAX=20
# Rate-limit window for token refresh in seconds (default: 60)
#OXICLOUD_RATE_LIMIT_REFRESH_WINDOW_SECS=60
# Consecutive failed logins before account lockout (default: 5)
#OXICLOUD_LOCKOUT_MAX_FAILURES=5
# Account lockout duration in seconds (default: 900 = 15 minutes)
#OXICLOUD_LOCKOUT_DURATION_SECS=900
# -----------------------------------------------------------------------------
# FEATURE FLAGS
@@ -96,6 +133,85 @@ DATABASE_URL=postgres://postgres:postgres@localhost:5432/oxicloud
# Enable search functionality (default: true)
#OXICLOUD_ENABLE_SEARCH=true
# Enable music playlists and audio metadata (default: true)
#OXICLOUD_ENABLE_MUSIC=true
# Expose other OxiCloud users as a read-only "system" address book
# at GET /api/address-books (default: true)
# Set to false to prevent users from browsing the user directory.
#OXICLOUD_EXPOSE_SYSTEM_USERS=true
# -----------------------------------------------------------------------------
# STORAGE BACKEND
# -----------------------------------------------------------------------------
# Blob storage backend: local (default), s3, or azure
#OXICLOUD_STORAGE_BACKEND=local
# --- S3-Compatible (AWS S3, Backblaze B2, Cloudflare R2, MinIO) ---
# Used when OXICLOUD_STORAGE_BACKEND=s3
# S3 bucket name (required)
#OXICLOUD_S3_BUCKET=my-oxicloud-bucket
# AWS region (default: us-east-1)
#OXICLOUD_S3_REGION=us-east-1
# Access credentials
#OXICLOUD_S3_ACCESS_KEY=
#OXICLOUD_S3_SECRET_KEY=
# Custom endpoint for non-AWS providers (e.g. MinIO, R2, B2)
#OXICLOUD_S3_ENDPOINT_URL=https://s3.example.com
# Force path-style URLs — required for MinIO, Cloudflare R2 (default: false)
#OXICLOUD_S3_FORCE_PATH_STYLE=false
# --- Azure Blob Storage ---
# Used when OXICLOUD_STORAGE_BACKEND=azure
# Storage account name (required)
#OXICLOUD_AZURE_ACCOUNT_NAME=
# Storage account key (or use SAS token below)
#OXICLOUD_AZURE_ACCOUNT_KEY=
# Blob container name (required)
#OXICLOUD_AZURE_CONTAINER=oxicloud
# SAS token (alternative to account key)
#OXICLOUD_AZURE_SAS_TOKEN=
# --- Local Disk Cache for Remote Backends ---
# LRU cache that speeds up repeated reads from S3 or Azure.
# Enable disk cache (default: false)
#OXICLOUD_STORAGE_CACHE_ENABLED=false
# Maximum cache size in bytes (default: 53687091200 = 50 GB)
#OXICLOUD_STORAGE_CACHE_MAX_SIZE=53687091200
# Cache directory (default: {STORAGE_PATH}/.blob-cache)
#OXICLOUD_STORAGE_CACHE_PATH=
# --- Client-Side Encryption ---
# AES-256-GCM encryption applied to blobs before writing to any backend.
# WARNING: losing the key means losing all data. Back it up securely.
# Enable at-rest blob encryption (default: false)
#OXICLOUD_STORAGE_ENCRYPTION_ENABLED=false
# Base64-encoded 32-byte key; generate with: openssl rand -base64 32
#OXICLOUD_STORAGE_ENCRYPTION_KEY=
# --- Retry Policy (Remote Backends) ---
# Exponential backoff retries for transient errors on S3 and Azure.
# Enable retry (default: true)
#OXICLOUD_STORAGE_RETRY_ENABLED=true
# Maximum number of retry attempts (default: 3)
#OXICLOUD_STORAGE_RETRY_MAX_RETRIES=3
# Initial backoff in milliseconds (default: 100)
#OXICLOUD_STORAGE_RETRY_INITIAL_BACKOFF_MS=100
# Maximum backoff cap in milliseconds (default: 10000)
#OXICLOUD_STORAGE_RETRY_MAX_BACKOFF_MS=10000
# Backoff multiplier per retry (default: 2.0)
#OXICLOUD_STORAGE_RETRY_BACKOFF_MULTIPLIER=2.0
# -----------------------------------------------------------------------------
# OPENID CONNECT (OIDC) / SSO CONFIGURATION
# -----------------------------------------------------------------------------
@@ -170,6 +286,37 @@ OXICLOUD_WOPI_ENABLED=false
# WOPI lock expiration in seconds (default: 1800 = 30 minutes)
#OXICLOUD_WOPI_LOCK_TTL_SECS=1800
# -----------------------------------------------------------------------------
# NEXTCLOUD COMPATIBILITY
# -----------------------------------------------------------------------------
# Enables the Nextcloud-compatible API layer for clients that speak the
# Nextcloud protocol (desktop sync, mobile apps, Nextcloud Talk, etc.)
# Enable Nextcloud compatibility (default: false)
#OXICLOUD_NEXTCLOUD_ENABLED=false
# Instance ID suffix used in oc:id formatting (default: ocnca)
#OXICLOUD_NEXTCLOUD_INSTANCE_ID=ocnca
# Emulated Nextcloud version reported to clients (default: 28.0.4)
# Clients use this to decide which protocol features to enable.
#OXICLOUD_NEXTCLOUD_VERSION=28.0.4
# -----------------------------------------------------------------------------
# PROXY
# -----------------------------------------------------------------------------
# Use this section if you are running OxiCloud behind a reverse proxy.
# Trusted Proxy CIDRs — comma-separated list of CIDR blocks whose
# X-Forwarded-For / X-Real-IP headers will be trusted for client IP detection.
# Leave unset if OxiCloud is directly exposed (no proxy).
# Example: 127.0.0.1/32,10.0.0.0/8,172.16.0.0/12,::1/128
#OXICLOUD_TRUST_PROXY_CIDR=
# DEPRECATED — use OXICLOUD_TRUST_PROXY_CIDR instead
#OXICLOUD_TRUST_PROXY_HEADERS=
# -----------------------------------------------------------------------------
# MEMORY ALLOCATOR TUNING (IMPORTANT FOR RAM USAGE)
# -----------------------------------------------------------------------------
@@ -201,16 +348,3 @@ MIMALLOC_PURGE_DELAY=0
# When enabled with Linux Transparent Huge Pages (THP), partially-used 2 MiB
# pages inflate the reported RSS by up to 20-30 MiB.
MIMALLOC_ALLOW_LARGE_OS_PAGES=0
# -----------------------------------------------------------------------------
# PROXY
# -----------------------------------------------------------------------------
# Use this section if you are running OxiCloud behind a proxy
# Trusted Proxy IPs. Format: coma separated list of CIDR
# (default not defined = server without proxy)
# if defined and proxy's IPs match, client_ip will be defined from
# `X-Forwarded-For` / `X-Real-Ip`
#OXICLOUD_TRUST_PROXY_CIDR=192.168.0.1/32,10.1.2.0/24