env.sample

# ============================================
# DEPLOYMENT MODE SELECTION
# ============================================
# Optional: Explicitly declare deployment mode (ADR-021)
# If not set, mode is auto-detected from other settings
# Valid values: single_user_basic, multi_user_basic, oauth_single_audience,
#               oauth_token_exchange, smithery
#
# Recommendation: Set this for clarity and to catch configuration errors early
#MCP_DEPLOYMENT_MODE=oauth_single_audience

# ============================================
# COMMON SETTINGS (Required for all modes)
# ============================================
# Your Nextcloud instance URL (without trailing slash)
NEXTCLOUD_HOST=

# ============================================
# SINGLE-USER BASICAUTH MODE
# ============================================
# Simplest deployment - one user, credentials in environment
# Use for: Personal instances, local development, testing
#
# Required:
NEXTCLOUD_USERNAME=
NEXTCLOUD_PASSWORD=
#
# Optional features (semantic search, document processing):
# See "Optional Features" section below

# ============================================
# MULTI-USER BASICAUTH MODE
# ============================================
# Users provide credentials in request headers (pass-through)
# Use for: Multi-user without OAuth, simple shared deployments
#
# Required:
#ENABLE_MULTI_USER_BASIC_AUTH=true
#
# Optional - Background Operations (for semantic search, future features):
# Enable background token storage using app passwords (via Astrolabe)
# Required for semantic search in multi-user mode
# Note: ENABLE_SEMANTIC_SEARCH automatically enables this in multi-user modes
#ENABLE_BACKGROUND_OPERATIONS=true
#NEXTCLOUD_OIDC_CLIENT_ID=
#NEXTCLOUD_OIDC_CLIENT_SECRET=
#TOKEN_ENCRYPTION_KEY=
#TOKEN_STORAGE_DB=/app/data/tokens.db
#
# Optional features (semantic search, document processing):
# See "Optional Features" section below

# ============================================
# OAUTH SINGLE-AUDIENCE MODE (Recommended)
# ============================================
# Multi-user OAuth with single-audience tokens
# Use for: Multi-user production deployments, enhanced security
# Tokens work for both MCP server and Nextcloud APIs (pass-through)
#
# Required: None (uses Dynamic Client Registration if credentials not provided)
#
# Optional - Pre-registered OAuth Client:
# If you pre-register the client instead of using DCR:
#NEXTCLOUD_OIDC_CLIENT_ID=
#NEXTCLOUD_OIDC_CLIENT_SECRET=
#
# Optional - Background Operations (for semantic search, future features):
# Enable refresh token storage for offline access
# Note: ENABLE_SEMANTIC_SEARCH automatically enables this in multi-user modes
#ENABLE_BACKGROUND_OPERATIONS=true
#TOKEN_ENCRYPTION_KEY=
#TOKEN_STORAGE_DB=/app/data/tokens.db
#
# Optional - Custom OIDC Discovery:
# Auto-detected from NEXTCLOUD_HOST if not set
#NEXTCLOUD_OIDC_DISCOVERY_URL=
#
# Optional - Custom Scopes:
# Default: openid profile email offline_access notes:* calendar:* contacts:* tables:* webdav:* deck:* cookbook:*
#NEXTCLOUD_OIDC_SCOPES=openid profile email notes:* calendar:*
#
# MCP Server URL (for OAuth redirects):
#NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
#
# Optional features (semantic search, document processing):
# See "Optional Features" section below

# ============================================
# OAUTH TOKEN EXCHANGE MODE (Advanced)
# ============================================
# Multi-user OAuth with RFC 8693 token exchange
# Use for: Advanced deployments requiring separate MCP and Nextcloud tokens
# MCP tokens are separate from Nextcloud tokens
#
# Required:
#ENABLE_TOKEN_EXCHANGE=true
#
# Optional - Pre-registered OAuth Client:
# If you pre-register the client instead of using DCR:
#NEXTCLOUD_OIDC_CLIENT_ID=
#NEXTCLOUD_OIDC_CLIENT_SECRET=
#
# Optional - Token Exchange Configuration:
# Cache TTL in seconds (default: 300 = 5 minutes)
#TOKEN_EXCHANGE_CACHE_TTL=300
#
# Optional - Background Operations:
# Note: ENABLE_SEMANTIC_SEARCH automatically enables this in multi-user modes
#ENABLE_BACKGROUND_OPERATIONS=true
#TOKEN_ENCRYPTION_KEY=
#TOKEN_STORAGE_DB=/app/data/tokens.db
#
# Optional - Custom OIDC Discovery:
#NEXTCLOUD_OIDC_DISCOVERY_URL=
#
# MCP Server URL (for OAuth redirects):
#NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
#
# Optional features (semantic search, document processing):
# See "Optional Features" section below

# ============================================
# SMITHERY STATELESS MODE
# ============================================
# Stateless multi-tenant deployment for Smithery platform
# Configuration comes from session URL parameters
# No persistent storage, no OAuth, no vector sync
#
# Required: None (all config from session URL)
# This mode is activated automatically when deployed to Smithery

# ============================================
# OPTIONAL FEATURES (All Deployment Modes)
# ============================================

# ===== SEMANTIC SEARCH =====
# AI-powered semantic search across Nextcloud content
# Requires: Qdrant vector database + embedding provider (Ollama, Bedrock, or Simple fallback)
#
# Enable semantic search:
#ENABLE_SEMANTIC_SEARCH=true
#
# Note for Multi-User Modes:
# ENABLE_SEMANTIC_SEARCH automatically enables background operations when needed
# No need to set ENABLE_BACKGROUND_OPERATIONS separately
# The server will automatically request refresh tokens and store them encrypted
#
# Vector Database - Choose ONE mode:
# 1. In-memory (default): Set neither QDRANT_URL nor QDRANT_LOCATION
# 2. Persistent local: Set QDRANT_LOCATION=/path/to/data
# 3. Network: Set QDRANT_URL=http://qdrant:6333
#
#QDRANT_URL=http://qdrant:6333
#QDRANT_LOCATION=:memory:
#QDRANT_API_KEY=
#QDRANT_COLLECTION=nextcloud_content
#
# Embedding Provider - Choose ONE:
# 1. Ollama (recommended for local deployment):
#OLLAMA_BASE_URL=http://ollama:11434
#OLLAMA_EMBEDDING_MODEL=nomic-embed-text
#OLLAMA_VERIFY_SSL=true
#
# 2. Amazon Bedrock (for AWS deployments):
#AWS_REGION=us-east-1
#BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
# Optional: AWS credentials (uses credential chain if not set)
#AWS_ACCESS_KEY_ID=
#AWS_SECRET_ACCESS_KEY=
#
# 3. Simple (automatic fallback, no configuration needed)
# Uses basic in-memory embeddings if no provider configured
#
# Document Chunking:
# Configure how documents are split before embedding
#DOCUMENT_CHUNK_SIZE=512
#DOCUMENT_CHUNK_OVERLAP=50

# ===== SEMANTIC SEARCH TUNING =====
# Advanced parameters for vector sync background operations
# Only modify if you understand the implications
#
# Document scan interval in seconds (default: 300 = 5 minutes)
#VECTOR_SYNC_SCAN_INTERVAL=300
#
# Concurrent indexing workers (default: 3)
#VECTOR_SYNC_PROCESSOR_WORKERS=3
#
# Max queued documents (default: 10000)
#VECTOR_SYNC_QUEUE_MAX_SIZE=10000

# ===== DOCUMENT PROCESSING =====
# Extract text from PDFs, images, DOCX, etc. for semantic search
# Disabled by default
#
#ENABLE_DOCUMENT_PROCESSING=false
#DOCUMENT_PROCESSOR=unstructured
#
# Unstructured.io Processor (recommended):
#ENABLE_UNSTRUCTURED=false
#UNSTRUCTURED_API_URL=http://unstructured:8000
#UNSTRUCTURED_TIMEOUT=120
#UNSTRUCTURED_STRATEGY=auto
#UNSTRUCTURED_LANGUAGES=eng,deu
#PROGRESS_INTERVAL=10
#
# Tesseract OCR (lightweight, images only):
#ENABLE_TESSERACT=false
#TESSERACT_CMD=/usr/bin/tesseract
#TESSERACT_LANG=eng
#
# Custom Processor (your own API):
#ENABLE_CUSTOM_PROCESSOR=false
#CUSTOM_PROCESSOR_NAME=my_ocr
#CUSTOM_PROCESSOR_URL=http://localhost:9000/process
#CUSTOM_PROCESSOR_API_KEY=
#CUSTOM_PROCESSOR_TIMEOUT=60
#CUSTOM_PROCESSOR_TYPES=application/pdf,image/jpeg,image/png

# ===== SECURITY & ADVANCED =====
# Cookie security (browser UI)
# Auto-detects from NEXTCLOUD_HOST protocol if not set
#COOKIE_SECURE=true

# ============================================
# DEPRECATED VARIABLES (Backward Compatibility)
# ============================================
# These variables still work but will be removed in v1.0.0
# Please migrate to new names:
#
# Old Name                  → New Name
# VECTOR_SYNC_ENABLED      → ENABLE_SEMANTIC_SEARCH
# ENABLE_OFFLINE_ACCESS    → ENABLE_BACKGROUND_OPERATIONS
#
# Migration is optional - both old and new names work
# Deprecation warnings will be logged when old names are used