From 8b08ee165ddf091a181ad93edf936eec9103af29 Mon Sep 17 00:00:00 2001 From: Edouard Vanbelle Date: Sun, 10 May 2026 22:12:55 +0200 Subject: [PATCH] doc: update example.env and docs/config/env.md --- docs/config/env.md | 134 +++++++++++++++++++++++++++++++----- example.env | 168 ++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 268 insertions(+), 34 deletions(-) diff --git a/docs/config/env.md b/docs/config/env.md index e207cb87..158d55c5 100644 --- a/docs/config/env.md +++ b/docs/config/env.md @@ -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 `/.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 | diff --git a/example.env b/example.env index 8f61608e..f330abf8 100644 --- a/example.env +++ b/example.env @@ -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 -