> ## Documentation Index > Fetch the complete documentation index at: https://docs.onyx.app/llms.txt > Use this file to discover all available pages before exploring further. # Configure Onyx > How to configure Onyx using environment variables and deployment files This page is for configuring your **deployment**. To find out more about configuring the Onyx app, checkout our [Admin docs](/admins/overview)! ## Configuring Onyx Deployments Onyx offers a wide range of deployment-level configuration options. These are controlled via environment variables or through your deployment files. ## Onyx Lite Onyx Lite is a minimal deployment of Onyx designed for teams that only need the core LLM chat experience without connectors or RAG search. It is ideal for resource-constrained environments, quick evaluations, or use cases where you want to bring your own LLM and tools without ingesting external data sources. ### What's Included Onyx Lite retains the following capabilities: * LLM chat conversations * Tools (including code interpreter in Docker deployments) * User file uploads * Projects * Agent knowledge * Assistants (without RAG retrieval) ### What's Removed To reduce resource requirements, Onyx Lite disables: * **Vespa** (vector database) — no document indexing or RAG search * **Redis** — PostgreSQL is used for caching and session management instead * **Model servers** — no local embedding models (LLM inference is handled by your configured provider) * **Celery background workers** — the API server handles background work directly * **MinIO / S3 file storage** — PostgreSQL is used for file storage instead * **Connectors** — all data source connectors are disabled ### How It Works Onyx Lite is not a separate application. It uses the same Onyx images with a different configuration that consolidates all storage onto PostgreSQL and disables the vector database. The key environment variables that drive this are: | Variable | Lite Value | Full Onyx Default | Purpose | | -------------------- | ---------- | ----------------- | ---------------------------------------------------- | | `DISABLE_VECTOR_DB` | `true` | `false` | Disables Vespa, connectors, and RAG search | | `CACHE_BACKEND` | `postgres` | `redis` | Uses PostgreSQL for caching instead of Redis | | `AUTH_BACKEND` | `postgres` | `redis` | Uses PostgreSQL for sessions instead of Redis | | `FILE_STORE_BACKEND` | `postgres` | `s3` | Uses PostgreSQL for file storage instead of S3/MinIO | Onyx Lite cannot be used with the Craft feature (`ENABLE_CRAFT`). If you don't have a `.env` file: ```bash theme={null} cd onyx/deployment/docker_compose cp env.prod.template .env # If applicable cp env.nginx.template .env.nginx ``` The template files have a subset of common environment variables provided for you. You can add more environment variables (listed below) to these `.env` files. Some configuration options must be set in your Docker Compose file. The Docker Compose file you use to launch Onyx is the one you will need to modify. Likely either `docker-compose.dev.yml` or `docker-compose.prod.yml`. ### Deploying Onyx Lite with Docker Compose Onyx Lite is deployed using a Docker Compose override file that layers on top of your base Compose file. The override moves non-essential services (Vespa, Redis, model servers, background workers) into Docker Compose [profiles](https://docs.docker.com/compose/how-tos/profiles/) so they do not start by default. **Quick start:** ```bash theme={null} cd onyx/deployment/docker_compose docker compose -f docker-compose.yml -f docker-compose.onyx-lite.yml up -d ``` With development ports exposed: ```bash theme={null} docker compose -f docker-compose.yml -f docker-compose.onyx-lite.yml \ -f docker-compose.dev.yml up -d --wait ``` Services started in Lite mode: | Service | Description | | | ----------------------------------------- | ---------------------------------------------- | ------------------------------------------------- | | api\_server | Onyx API server (also handles background work) | | | web\_server | Next.js frontend | | | relational\_db | PostgreSQL database | | | nginx | Reverse proxy | | | Services not started (moved to profiles): | | | | Service | Profile | Bring back with | | -------------------------- | ---------------- | ----------------------------------------- | | background (Celery) | background | --profile background (also needs --profile redis) | | cache (Redis) | redis | --profile redis | | index (Vespa) | vectordb | --profile vectordb | | indexing\_model\_server | vectordb | --profile vectordb | | inference\_model\_server | inference | --profile inference | You can selectively bring services back by adding `--profile ` flags. For example, to run Lite with Redis: ```bash theme={null} docker compose -f docker-compose.yml -f docker-compose.onyx-lite.yml \ --profile redis up -d ``` The .env file setup is the same as a standard Docker deployment. Lite-specific environment variables (DISABLE\_VECTOR\_DB, CACHE\_BACKEND, AUTH\_BACKEND, FILE\_STORE\_BACKEND) are set automatically by the override file — you do not need to add them to your .env. Kubernetes deployments are configured using Helm charts. We have provided a `values.yaml` file where you can set all environment variables. ```bash theme={null} cd onyx/deployment/helm/charts/onyx vim values.yaml ``` Add environment variables and secrets to the `configMap` and `auth.secrets` sections. A subset of common configuration options are provided for you. You can add more environment variables (listed below) to these sections. ### Deploying Onyx Lite with Helm Onyx Lite is deployed by providing the values-lite.yaml file when installing the Helm chart. This values file disables the vector database, Redis, and all Celery workers, leaving only the API server, web server, and PostgreSQL. Quick start: ``` helm install onyx ./deployment/helm/charts/onyx \ -f ./deployment/helm/charts/onyx/values-lite.yaml ``` To merge with your own overrides (custom domain, auth, LLM config, etc.): ``` helm install onyx ./deployment/helm/charts/onyx \ -f ./deployment/helm/charts/onyx/values-lite.yaml \ -f my-overrides.yaml ``` You can always upgrade from Lite to a full deployment later by re-installing with the default values.yaml (without values-lite.yaml). This will bring up Opensearch, Redis, and all background workers. Many configuration options are available in the Admin Panel! This page only covers deployment-level configuration. ## Commonly Configured Options ### Authentication Set up email and password authentication. Authenticate with Google accounts. Single-sign on with OpenID Connect (OIDC) Single-sign on with Security Assertion Markup Language (SAML) ### Custom Domain To host Onyx on a custom domain, set the `WEB_DOMAIN` environment variable and update your DNS records to point to your public Onyx deployment IP. For additional instructions, read the [EC2 Deployment Guide](/deployment/cloud/aws/ec2)! ### SSL If using Docker, the `init-letsencrypt.sh` script in `onyx/deployment/docker_compose` will automatically generate a Let's Encrypt certificate and launch Onyx with SSL enabled. ### Web Search To enable the Web Search Tool, set the `EXA_API_KEY` environment variable. Web Search in Onyx is continually developing and these instructions will be updated as we make improvements. ### Logging When self-hosting Onyx, you can configure the level of detail in the logs. This is helpful when troubleshooting issues. If using Docker, set `LOG_LEVEL` to `debug` in each container of your Docker Compose file. If using Kubernetes, set `LOG_LEVEL` to `debug` in your `values.yaml` file. ### Observability You can connect your observability tools to Onyx. We support the following providers: **Braintrust (recommended)** Braintrust is what we use internally for the cloud version of Onyx. Set the following environment variables: ```bash theme={null} BRAINTRUST_PROJECT="Your project name" BRAINTRUST_API_KEY="sk-..." ``` **Langfuse** ```bash theme={null} LANGFUSE_SECRET_KEY="sk-..." LANGFUSE_PUBLIC_KEY="pk-..." LANGFUSE_BASE_URL="https://cloud.langfuse.com" # Or "https://us.cloud.langfuse.com" ``` ## Onyx Environment Variables This is not an exhaustive list of all Onyx environment variables. `SKIP_WARM_UP`: Skip application warm-up process for hot-reloading the `API server`. Only set this for development purposes. `WEB_DOMAIN`: Set this if you are deploying Onyx on a custom domain. `DISABLE_GENERATIVE_AI`: Disable generative AI features. `DISABLE_USER_KNOWLEDGE`: Controls whether users can use the My Documents feature with assistants. `ONYX_QUERY_HISTORY_TYPE`: Controls query history reports (show user emails, anonymous, no queries) `AUTH_TYPE`: Authentication type (disabled, basic, oauth, etc.) `PASSWORD_MIN_LENGTH`: For basic auth. The minimum password length requirement `PASSWORD_MAX_LENGTH`: For basic auth. The maximum password length requirement `PASSWORD_REQUIRE_UPPERCASE`: For basic auth. Require uppercase letters in passwords `PASSWORD_REQUIRE_LOWERCASE`: For basic auth. Require lowercase letters in passwords `PASSWORD_REQUIRE_DIGIT`: For basic auth. Require digits in passwords `PASSWORD_REQUIRE_SPECIAL_CHAR`: For basic auth. Require special characters in passwords `ENCRYPTION_KEY_SECRET`: Enterprise Edition only. Key for encrypting connector credentials, API keys, etc. `MASK_CREDENTIAL_PREFIX`: Mask connector credentials in the admin UI. Turn off if admins should see the credentials in the admin panel. `SESSION_EXPIRE_TIME_SECONDS`: Session expiration time in seconds. `AUTH_COOKIE_EXPIRE_TIME_SECONDS`: JWT token validity duration in seconds. `VALID_EMAIL_DOMAINS`: Comma-separated list of allowed email domains. `REQUIRE_EMAIL_VERIFICATION`: Require email verification for registration `TRACK_EXTERNAL_IDP_EXPIRY`: Honor the `expires_at` field returned by the external identity provider. Disabled be default because many auth providers have very short expiry times. `OAUTH_CLIENT_ID`: For both Google OAuth and OIDC. `OAUTH_CLIENT_SECRET`: For both Google OAuth and OIDC. `OPENID_CONFIG_URL`: For OIDC. `GOOGLE_OAUTH_SCOPE_OVERRIDE`: For Google OAuth login (`AUTH_TYPE=google_oauth` or `cloud`). Comma-separated list of scopes to request from Google instead of the defaults (`openid,email,profile`). Useful when the access token from login needs to be passed through to tool calls that require additional Google API scopes (i.e. when using Pass-Through OAuth for an MCP server). Any scopes added here must also be enabled on the OAuth client in Google Cloud Console. `OIDC_SCOPE_OVERRIDE`: For OIDC login (`AUTH_TYPE=oidc`). Comma-separated list of scopes to request from the OIDC provider instead of the defaults. Same use case as `GOOGLE_OAUTH_SCOPE_OVERRIDE`. `OIDC_PKCE_ENABLED`: For OIDC login. Set to `true` to enable PKCE in the OIDC login flow. Disabled by default for backwards compatibility. Set the following for basic auth email verification and invites. `SMTP_SERVER`: SMTP server hostname `SMTP_PORT`: SMTP server port `SMTP_USER`: SMTP username `SMTP_PASS`: SMTP password `EMAIL_FROM`: From email address `SENDGRID_API_KEY`: Alternative to SMTP for email delivery. `ENABLE_EMAIL_INVITES`: Enable email invitations `OAUTH_SLACK_CLIENT_ID`: Slack OAuth client ID for Slack bot. `OAUTH_SLACK_CLIENT_SECRET`: Slack OAuth client secret for Slack bot. `POSTGRES_USER`: PostgreSQL username `POSTGRES_PASSWORD`: PostgreSQL password `POSTGRES_HOST`: PostgreSQL host `POSTGRES_PORT`: PostgreSQL port `POSTGRES_DB`: PostgreSQL database name `POSTGRES_API_SERVER_POOL_SIZE`: API server connection pool size `POSTGRES_API_SERVER_POOL_OVERFLOW`: API server pool overflow `POSTGRES_API_SERVER_READ_ONLY_POOL_SIZE`: Read-only pool size `POSTGRES_API_SERVER_READ_ONLY_POOL_OVERFLOW`: Read-only pool overflow `POSTGRES_USE_NULL_POOL`: Use null connection pool `POSTGRES_POOL_PRE_PING`: Enable connection pre-ping `POSTGRES_POOL_RECYCLE`: Pool recycle timeout in seconds `USE_IAM_AUTH`: Use IAM authentication for database `DB_READONLY_USER`: Read-only database user `DB_READONLY_PASSWORD`: Read-only database password `REDIS_SSL`: Enable SSL for Redis connections `REDIS_HOST`: Redis host `REDIS_PORT`: Redis port `REDIS_PASSWORD`: Redis password `REDIS_REPLICA_HOST`: Redis replica host `REDIS_DB_NUMBER`: Redis database number `REDIS_DB_NUMBER_CELERY_RESULT_BACKEND`: Celery result backend database number `REDIS_DB_NUMBER_CELERY`: Celery broker database number `REDIS_HEALTH_CHECK_INTERVAL`: Health check interval `REDIS_POOL_MAX_CONNECTIONS`: Maximum pool connections `REDIS_SSL_CERT_REQS`: SSL certificate requirements `REDIS_SSL_CA_CERTS`: SSL CA certificates `VESPA_HOST`: Vespa host `VESPA_CONFIG_SERVER_HOST`: Vespa config server host `VESPA_PORT`: Vespa port `VESPA_TENANT_PORT`: Vespa tenant port `NUM_RETRIES_ON_STARTUP`: Startup connection attempts `VESPA_CLOUD_URL`: Vespa Cloud URL `VESPA_CLOUD_CERT_PATH`: Vespa Cloud certificate path `VESPA_CLOUD_KEY_PATH`: Vespa Cloud key path `MANAGED_VESPA`: Use managed Vespa (Vespa Cloud) `VESPA_REQUEST_TIMEOUT`: Request timeout in seconds `VESPA_LANGUAGE_OVERRIDE`: Force Vespa language (en, de, etc.) `CELERY_RESULT_EXPIRES`: Result expiration time in seconds `CELERY_BROKER_POOL_LIMIT`: Broker connection pool limit `CELERY_WORKER_LIGHT_CONCURRENCY`: Light worker concurrency `CELERY_WORKER_LIGHT_PREFETCH_MULTIPLIER`: Light worker prefetch multiplier `CELERY_WORKER_DOCPROCESSING_CONCURRENCY`: Document processing worker concurrency `CELERY_WORKER_DOCFETCHING_CONCURRENCY`: Document fetching worker concurrency `CELERY_WORKER_KG_PROCESSING_CONCURRENCY`: Knowledge graph processing worker concurrency These rate limits apply to auth endpoints `RATE_LIMIT_WINDOW_SECONDS`: Rate limiting window in seconds `RATE_LIMIT_MAX_REQUESTS`: Maximum requests per window `REQUEST_TIMEOUT_SECONDS`: Default request timeout `INDEX_BATCH_SIZE`: Batch size during indexing `DISABLE_INDEX_UPDATE_ON_SWAP`: Disable primary index updates during embedding model swaps `ENABLE_MULTIPASS_INDEXING`: Enable multipass indexing for better accuracy `ENABLE_CONTEXTUAL_RAG`: Enable contextual retrieval `SKIP_METADATA_IN_CHUNK`: Skip metadata in chunks `INDEXING_SIZE_WARNING_THRESHOLD`: Size warning threshold in bytes `INDEXING_EMBEDDING_MODEL_NUM_THREADS`: Embedding model threads `CONTINUE_ON_CONNECTOR_FAILURE`: Continue indexing on connector failures `MAX_DOCUMENT_CHARS`: Maximum document characters `MAX_FILE_SIZE_BYTES`: Maximum file size in bytes `USE_DOCUMENT_SUMMARY`: Use document summary for contextual RAG `USE_CHUNK_SUMMARY`: Use chunk summary for contextual RAG Most of the settings below can be configured in the admin UI. **General Connector Settings** `ENABLED_CONNECTOR_TYPES`: Comma-separated list of enabled connector types `LEAVE_CONNECTOR_ACTIVE_ON_INITIALIZATION_FAILURE`: Keep connector active on init failure `CURATORS_CANNOT_VIEW_OR_EDIT_NON_OWNED_ASSISTANTS`: Restrict curator access **Web Connector** `WEB_CONNECTOR_VALIDATE_URLS`: Validate URLs in web connector `HTML_BASED_CONNECTOR_TRANSFORM_LINKS_STRATEGY`: Link transformation strategy `PARSE_WITH_TRAFILATURA`: Use Trafilatura for HTML parsing **Confluence Connector** `OAUTH_CONFLUENCE_CLOUD_CLIENT_ID`: Confluence Cloud OAuth client ID `OAUTH_CONFLUENCE_CLOUD_CLIENT_SECRET`: Confluence Cloud OAuth client secret `CONFLUENCE_CONNECTOR_LABELS_TO_SKIP`: Labels to skip during indexing `CONFLUENCE_CONNECTOR_ATTACHMENT_SIZE_THRESHOLD`: Attachment size threshold `CONFLUENCE_CONNECTOR_ATTACHMENT_CHAR_COUNT_THRESHOLD`: Attachment character threshold `CONFLUENCE_CONNECTOR_USER_PROFILES_OVERRIDE`: User profiles override JSON `CONFLUENCE_TIMEZONE_OFFSET`: Timezone offset for CQL queries **Google Drive Connector** `OAUTH_GOOGLE_DRIVE_CLIENT_ID`: Google Drive OAuth client ID `OAUTH_GOOGLE_DRIVE_CLIENT_SECRET`: Google Drive OAuth client secret `MAX_DRIVE_WORKERS`: Maximum Google Drive workers `GOOGLE_DRIVE_CONNECTOR_SIZE_THRESHOLD`: File size threshold for Google Drive **SharePoint Connector** `SHAREPOINT_CONNECTOR_SIZE_THRESHOLD`: File size threshold for SharePoint **Jira Connector** `JIRA_CONNECTOR_LABELS_TO_SKIP`: Labels to skip during indexing `JIRA_CONNECTOR_MAX_TICKET_SIZE`: Maximum ticket size in bytes **GitHub Connector** `GITHUB_CONNECTOR_BASE_URL`: GitHub base URL (for enterprise) **GitLab Connector** `GITLAB_CONNECTOR_INCLUDE_CODE_FILES`: Include code files in indexing **Gong Connector** `GONG_CONNECTOR_START_TIME`: Start time for Gong connector **Notion Connector** `NOTION_CONNECTOR_DISABLE_RECURSIVE_PAGE_LOOKUP`: Disable recursive page lookup **Zendesk Connector** `ZENDESK_CONNECTOR_SKIP_ARTICLE_LABELS`: Article labels to skip **Egnyte Integration** `EGNYTE_CLIENT_ID`: Egnyte OAuth client ID `EGNYTE_CLIENT_SECRET`: Egnyte OAuth client secret **Linear Integration** `LINEAR_CLIENT_ID`: Linear OAuth client ID `LINEAR_CLIENT_SECRET`: Linear OAuth client secret `ALLOW_SIMULTANEOUS_PRUNING`: Allow simultaneous pruning operations `MAX_PRUNING_DOCUMENT_RETRIEVAL_PER_MINUTE`: Maximum document retrieval rate during pruning `OKTA_PROFILE_TOOL_ENABLED`: Enable Okta profile tool `OKTA_API_TOKEN`: Okta API token for SSWS auth `LOG_ONYX_MODEL_INTERACTIONS`: Log Onyx model interactions `LOG_VESPA_TIMING_INFORMATION`: Log Vespa query performance `LOG_ENDPOINT_LATENCY`: Log endpoint latency `LOG_POSTGRES_LATENCY`: Log PostgreSQL latency `LOG_POSTGRES_CONN_COUNTS`: Log PostgreSQL connection counts `IMAGE_MODEL_NAME`: Image model name `AZURE_IMAGE_API_VERSION`: Azure OpenAI image API version `AZURE_IMAGE_API_KEY`: Azure OpenAI key used for image generation `AZURE_IMAGE_API_BASE`: Azure OpenAI endpoint base URL for image generation `AZURE_IMAGE_DEPLOYMENT_NAME`: Azure OpenAI image deployment namespace `AZURE_DALLE_API_VERSION`: Legacy alias for `AZURE_IMAGE_API_VERSION` (kept for backwards compatibility) `AZURE_DALLE_API_KEY`: Legacy alias for `AZURE_IMAGE_API_KEY` (kept for backwards compatibility) `AZURE_DALLE_API_BASE`: Legacy alias for `AZURE_IMAGE_API_BASE` (kept for backwards compatibility) `AZURE_DALLE_DEPLOYMENT_NAME`: Legacy alias for `AZURE_IMAGE_DEPLOYMENT_NAME` (kept for backwards compatibility) `IMAGE_SUMMARIZATION_SYSTEM_PROMPT`: System prompt for image summarization `IMAGE_SUMMARIZATION_USER_PROMPT`: User prompt for image summarization `S3_FILE_STORE_BUCKET_NAME`: S3 bucket name for file storage `S3_FILE_STORE_PREFIX`: S3 prefix for file storage `S3_ENDPOINT_URL`: S3 endpoint URL (for MinIO and other S3-compatible storage) `S3_VERIFY_SSL`: Verify SSL for S3 connections `S3_AWS_ACCESS_KEY_ID`: AWS access key ID for S3 `S3_AWS_SECRET_ACCESS_KEY`: AWS secret access key for S3 `DISABLE_TELEMETRY`: Disable anonymous usage telemetry `CUSTOM_ANSWER_VALIDITY_CONDITIONS`: Custom answer validity conditions `API_PREFIX`: Used to prepend a base path for all API routes. Set this to `/api` if you are running Onyx behind a reverse proxy that doesn't support stripping the `/api` prefix from requests to the `API server`. `API_KEY_HASH_ROUNDS`: Hash rounds for API keys `LLM_MODEL_UPDATE_API_URL`: LLM model update API endpoint `LITELLM_CUSTOM_ERROR_MESSAGE_MAPPINGS`: Custom error message mappings (JSON) `GEN_AI_MODEL_FALLBACK_MAX_TOKENS`: Maximum token limit for generative AI model fallback [Contact us](/deployment/miscellaneous/contact_us) to enable Enterprise Edition features! `DATA_PLANE_SECRET`: Secret for secure control/data plane communication `EXPECTED_API_KEY`: Additional security check for control plane API `CONTROL_PLANE_API_BASE_URL`: Control plane API base URL `DEV_MODE`: Enable development mode `INTEGRATION_TESTS_MODE`: Enable integration tests mode `MOCK_LLM_RESPONSE`: Boolean to create mock LLM responses for testing `POD_NAME`: Kubernetes pod name `POD_NAMESPACE`: Kubernetes pod namespace `AWS_REGION_NAME`: AWS region name `TARGET_AVAILABLE_TENANTS`: Number of pre-provisioned tenants to maintain `SYSTEM_RECURSION_LIMIT`: System recursion limit ## Enterprise Edition Environment Variables Enterprise Edition adds additional environment variables to Onyx. Setting this variable allows you to start your Onyx instance with pre-configured options that persist across restarts. `ENV_SEED_CONFIGURATION` accepts a JSON string with the following options: * `llms`: List of LLM configurations (name, provider, api\_key, api\_base, api\_version, custom\_config, default\_model\_name, fast\_default\_model\_name) * `admin_user_emails`: List of email addresses for automatic admin role assignment * `seeded_name`: Pre-set name for your Onyx instance * `seeded_logo_path`: Path to your logo within the assets folder This variable allows you to configure the number of rounds used in the SHA-256 Crypt hashing algorithm for API keys. * Default value: `535000` * Allowed range: `1000` to `999999999` Increasing this value enhances security but may impact performance. The default value provides a good balance for most use cases.