Environment Variables
Configuration is done via environment variables in the .env file created by the installer.
Starting from v1.8.0
Several variables that previously drove runtime behaviour are now first-boot seeds only. After the first successful startup the system_settings (and auth_settings) Postgres table is authoritative and changes apply without a restart. The env-var column below notes which variables are seeds vs. always-live.
Authentication
| Variable | Default | Description |
|---|---|---|
JWT_SECRET_KEY | (must be set) | Secret key for signing JWTs. Change this before deployment. Generate with: openssl rand -hex 32 |
JWT_ALGORITHM | HS256 | JWT signing algorithm |
ACCESS_TOKEN_EXPIRE_SECONDS | 900 | First-boot seed. Access token lifetime in seconds (default: 15 min). Managed at runtime via PATCH /api/admin/auth/settings after first boot. |
REFRESH_TOKEN_EXPIRE_SECONDS | 604800 | First-boot seed. Refresh token lifetime in seconds (default: 7 days). Managed at runtime after first boot. |
DEFAULT_ADMIN_USER | admin | Username for the default admin account created on first boot |
DEFAULT_ADMIN_PASSWORD | changeme | Password for the default admin account. Change this before deployment. |
DEFAULT_ADMIN_EMAIL | (optional) | Email seeded for the default admin user on first boot. Set this so the seeded admin can use email-based password reset immediately. |
MFA_ENCRYPTION_KEY | (must be set — v1.8.0+) | Fernet key used to encrypt TOTP secrets and OIDC client_secret values at rest. Supply via the mfa_encryption_key Docker secret. Required — the stack will not start without it. |
AUTH_REQUIRE_EMAIL | false | When true, creating or updating local users requires a non-empty email address. Recommended when enabling password reset. |
Generate a Fernet key for MFA_ENCRYPTION_KEY:
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
Then provide it via Docker secret:
echo "<generated-key>" | docker secret create mfa_encryption_key -
OIDC / SSO (v1.8.0+)
OIDC providers are primarily managed through the admin UI (stored in the oidc_providers Postgres table). The env vars below serve as a fallback when the table is empty and are useful for bootstrapping or scripted deployments.
| Variable | Description |
|---|---|
OIDC_PROVIDERS | Comma-separated list of provider names, e.g. entra,google |
OIDC_<NAME>_CLIENT_ID | Client ID for the named provider |
OIDC_<NAME>_DISCOVERY_URL | OIDC discovery document URL (.well-known/openid-configuration) |
OIDC_<NAME>_REDIRECT_URI | Redirect URI registered with the IdP |
OIDC_<NAME>_SCOPES | Space-separated scopes (default: openid email profile) |
OIDC_<NAME>_ADMIN_GROUPS | Comma-separated IdP group names whose members are auto-promoted to admin |
Client secrets must be supplied as Docker secrets (oidc_<name>_client_secret), not as plain env vars.
See the SSO / OIDC guide for full configuration instructions.
TLS / HTTPS (v1.8.0+)
| Variable | Default | Description |
|---|---|---|
TLS_ENABLED | 0 | Set to 1 to enable HTTPS termination in the bundled nginx. See the TLS / HTTPS guide. |
SERVER_NAME | (must be set when TLS enabled) | Fully-qualified domain name for the server (used in nginx server_name and HSTS headers) |
TLS_CERT_PATH | /etc/nginx/certs/fullchain.pem | Path to the TLS certificate (inside the nginx container) |
TLS_KEY_PATH | /etc/nginx/certs/privkey.pem | Path to the private key (inside the nginx container) |
HSTS_MAX_AGE | 31536000 | HSTS max-age in seconds (1 year). Set to 0 to disable HSTS. |
OCSP_STAPLING | on | Set to off for air-gapped deployments that cannot reach OCSP responders. |
Docker Compose env-file gotcha
Docker Compose only auto-loads a file literally named .env. If your TLS variables are in .env.local or another file, you must pass --env-file .env.local explicitly — otherwise TLS_ENABLED will fall back to 0.
Database & Cache
| Variable | Default | Description |
|---|---|---|
DATABASE_URL | (set by installer) | PostgreSQL connection string |
REDIS_URL | (set by installer) | Redis connection string |
QDRANT_URL | http://rag-db:6333 | Qdrant vector database connection URL. |
QDRANT_API_KEY | CHANGEME | API key for Qdrant authentication. Change this before deployment. |
Privacy
| Variable | Default | Description |
|---|---|---|
RAG_LOG_ANONYMISE | true | First-boot seed. Anonymise user identifiers in log output. Managed at runtime via system_settings. |
RAG_LOG_REDACT_QUERIES | true | First-boot seed. Redact query text from log output. Managed at runtime via system_settings. |
RAG_CONVERSATION_MAX_AGE_DAYS | 90 | First-boot seed. Automatically purge conversations older than this many days. Managed at runtime via system_settings. |
RAG_CONVERSATION_MAX_TURNS | 100 | First-boot seed. Maximum number of turns retained per conversation. Managed at runtime via system_settings. |
Runtime
| Variable | Default | Description |
|---|---|---|
LOG_LEVEL | INFO | First-boot seed. Logging verbosity (DEBUG, INFO, WARNING, ERROR). Managed at runtime via system_settings. |
RAG_AUDIT_RETENTION_DAYS | 365 | First-boot seed. Audit log retention period in days. Managed at runtime via system_settings. |
CONNECTOR_ALLOWED_PATHS | /app/docs | Colon-separated list of container-side paths that connectors are permitted to access. Always include /app/docs. |
INDEX_EXTRACTION_WORKERS | (set by installer) | Number of parallel workers for document text extraction |
BACKEND_WORKERS | 1 | Number of uvicorn worker processes. Increase for higher throughput on multi-core systems. Added in v1.2.1. |
DOCKER_PORT | 3000 | Host port mapped to the UI container |
Indexing (OCR & Tables) (v1.9.0+)
| Variable | Default | Description |
|---|---|---|
INDEXING_OCR_ENABLED | false | Enable OCR for scanned PDFs and image files (PNG/JPG/TIFF). OCR is additive: text-first extraction still uses the fast native path when text is available. |
INDEXING_OCR_LANGUAGES | eng | Tesseract language codes as a comma-separated list (for example eng,deu). |
INDEXING_TABLES_ENABLED | false | Enable additive table-row extraction for PDF, DOCX, Excel, and CSV documents. |
See OCR & Table Extraction for setup and re-index guidance.
Inference & Embedding
| Variable | Default | Description |
|---|---|---|
N_CTX | 8192 | Context window size in tokens requested from the inference runtime. Lower values reduce memory usage. Jetson default: 4096. A startup warning is logged if the configured value exceeds the model's actual capacity — see EFFECTIVE_N_CTX below. |
EFFECTIVE_N_CTX | (read-only) | Derived at startup from the inference runtime — the actual context window size in effect. This is the single source of truth used by the token budget manager. When N_CTX exceeds model capacity, EFFECTIVE_N_CTX reflects the model's real limit and a warning is emitted in the startup logs. |
N_THREADS | 8 | Number of CPU threads for inference. Jetson default: 6. |
N_GPU_LAYERS | 0 | Number of transformer layers offloaded to GPU. Set to -1 to offload all layers. Only applies when a CUDA-capable GPU is detected. |
EMBED_DEVICE | auto | Device for embedding model inference: auto (use CUDA if available, else CPU), cpu, or cuda. Added in v1.3.0. |
INFERENCE_URL | http://inference:8001 | URL of the llama-cpp-python inference server. |
INFERENCE_TIMEOUT_SECONDS | 120 | First-boot seed. Timeout for inference requests in seconds. Managed at runtime via system_settings. |
LLM_BACKEND | local | Chat inference backend: local (bundled inference container) or openai (OpenAI-compatible hosted API). |
OPENAI_API_KEY | (required when LLM_BACKEND=openai) | API key for OpenAI or an OpenAI-compatible provider. |
OPENAI_BASE_URL | (optional) | Override API base URL for OpenAI-compatible endpoints (for example Azure OpenAI or local compatible gateways). |
OPENAI_MODEL | (required when LLM_BACKEND=openai) | Chat model name used by the OpenAI backend. |
See Using OpenAI as the LLM backend for mode-specific behavior.
Email / Password Reset (v1.9.0+)
| Variable | Default | Description |
|---|---|---|
EMAIL_PROVIDER | console | Email delivery backend: console (logs reset links to stdout for development) or smtp. |
SMTP_HOST | (required when EMAIL_PROVIDER=smtp) | SMTP server host. |
SMTP_PORT | (required when EMAIL_PROVIDER=smtp) | SMTP server port. |
SMTP_USERNAME | (optional) | SMTP username (if your server requires authentication). |
SMTP_PASSWORD | (Docker secret) | SMTP password supplied via Docker secret. |
SMTP_FROM | (required when EMAIL_PROVIDER=smtp) | Sender address used for reset emails (for example DocBot <noreply@example.com>). |
SMTP_STARTTLS | (optional) | Enable STARTTLS negotiation on SMTP connections. |
SMTP_TLS | (optional) | Use implicit TLS SMTP mode when your mail server expects SMTPS. |
RATE_LIMIT_RESET | 10r/m | nginx rate limit for password reset endpoints (/api/auth/forgot-password, /api/auth/reset-password). |
RATE_LIMIT_RESET_BURST | 20 | Burst allowance for password reset endpoint rate limiting. |
See Email-based password reset for end-to-end setup and flow.
Query Pipeline
| Variable | Default | Description |
|---|---|---|
RAG_CLASSIFIER_LLM_ENABLED | false | Enable LLM-assisted hybrid query classifier. When true, ambiguous queries are disambiguated via the local inference server. When false (default), classification is fully deterministic. |
RAG_CLASSIFIER_LLM_MAX_TOKENS | 64 | Maximum tokens for the LLM classifier response. 64 is sufficient for the small JSON output. |
RAG_LOG_TOKEN_USAGE | false | First-boot seed. When true, logs per-request token budget usage. Managed at runtime via system_settings. |
RAG_QUERY_REWRITE_ENABLED | false | First-boot seed. Enable query rewriting for multi-turn conversations. Managed at runtime via system_settings. |
RAG_QUERY_REWRITE_MAX_TURNS | 3 | First-boot seed. Maximum prior turns used for query rewriting context. Managed at runtime via system_settings. |
RAG_MIN_CHUNK_LENGTH | 50 | First-boot seed. Minimum character length for indexed chunks. Managed at runtime via system_settings. |
Multi-worker, Scheduling & Retention (v1.9.1+)
| Variable | Default | Description |
|---|---|---|
JOB_STORE_BACKEND | auto | Job-state backend. auto uses Redis when reachable and falls back to in-memory with a one-shot warning; redis makes Redis a hard requirement; memory forces in-process only (single-replica deployments). |
JOB_STATE_TTL_SECONDS | 86400 | TTL applied to terminal job snapshots in Redis. In-flight jobs are persisted without a TTL. |
SCHEDULER_LEADER_LOCK_ENABLED | true | Enables a Redis-based leader lock so only one backend replica fires scheduled syncs per tick. Safe to leave on in single-replica deployments. |
SCHEDULER_LEADER_LOCK_TTL_SECONDS | 30 | TTL of the scheduler leader lock; renewed at TTL/3 by the current leader. |
RETENTION_SWEEPS_ENABLED | true | Enables the daily background sweeps for job_history and conversation retention. |
JOB_HISTORY_RETENTION_DAYS | 30 | Number of days of job_history rows retained by the daily sweep. |
INDEX_UPSERT_BATCH_SIZE | 256 | Caps the number of pending chunks held in memory before each flush + upsert to Qdrant. Applies to file, GitHub, and Google Drive indexers. |
ENABLE_API_DOCS | false | When true, exposes Swagger UI at /api/swagger, ReDoc at /api/redoc, and the OpenAPI JSON at /api/openapi.json. Off by default so production deployments do not publish their API surface. |
Database Connection Pool (v1.9.1+)
| Variable | Default | Description |
|---|---|---|
DB_POOL_SIZE | 10 | SQLAlchemy connection pool size for both async and sync engines. Ignored for SQLite. |
DB_MAX_OVERFLOW | 20 | Maximum overflow connections beyond DB_POOL_SIZE. |
DB_POOL_TIMEOUT | 30 | Seconds to wait for a connection before raising. |
DB_POOL_RECYCLE | 1800 | Seconds after which connections are recycled (helps with load-balanced Postgres timeouts). |