[PR #1395] [MERGED] docs: correct env-reference defaults that drifted from config.py and env.py #1361

New issue

Closed

opened 2026-10-18 14:19:07 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-18 14:19:07 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/open-webui/docs/pull/1395
Author: @silentoplayz
Created: 9/18/2026
Status: ✅ Merged
Merged: 9/18/2026
Merged by: @silentoplayz

Base: main ← Head: docs/env-defaults

📝 Commits (5)

6ab08a8 docs: correct env-reference defaults that drifted from config.py and env.py
8077917 docs: the local web fetch gate is a startup setting, not a persisted one
934f3c3 docs: label persisted and startup-only settings the way config.py registers them
1c48d27 docs: fix env-reference types, the Azure search value, and the splitter options against the code
70e49fe docs: use the variable names the code reads for Google Drive and the Playwright websocket

📊 Changes

1 file changed (+123 additions, -123 deletions)

View changed files

📝 docs/reference/env-configuration.mdx (+123 -123)

📄 Description

Summary

I compared every - Default: line in the environment variable reference against backend/open_webui/config.py and backend/open_webui/env.py, on dev and at the v0.11.3 tag. Most entries match. These did not, and each one below now states what the code does:

ENABLE_DIRECT_CONNECTIONS and ENABLE_AUTOCOMPLETE_GENERATION default to False, not True.
RAG_EMBEDDING_MODEL_TRUST_REMOTE_CODE and RAG_RERANKING_MODEL_TRUST_REMOTE_CODE default to True, not False.
DATABASE_ENABLE_SQLITE_WAL defaults to True, not False.
ENABLE_IMAGE_EDIT defaults to False, not true.
The four USER_PERMISSIONS_WORKSPACE_{MODELS,PROMPTS}_{IMPORT,EXPORT} flags default to False, not True, and are booleans.
TIKA_SERVER_URL defaults to http://tika:9998, not http://localhost:9998.
DOCUMENT_INTELLIGENCE_MODEL defaults to prebuilt-layout, not None.
CODE_EXECUTION_JUPYTER_TIMEOUT defaults to 60, and the five CODE_INTERPRETER_JUPYTER_* settings fall back to their CODE_EXECUTION_JUPYTER_* counterparts, which the page did not say.
PLAYWRIGHT_TIMEOUT defaults to 10000 milliseconds, not empty.
AIOHTTP_CLIENT_TIMEOUT is unset by default, which means no timeout. 300 is only the fallback for a value that fails to parse. The page had the two the other way round.
WEBUI_URL, DEFAULT_LOCALE and AUDIO_STT_MODEL default to an empty string, not http://localhost:3000, en and whisper-1. For the locale the page now says what an empty value does (the browser's language, then en-US).
BING_SEARCH_V7_SUBSCRIPTION_KEY listed the endpoint URL as its default. The URL now sits on BING_SEARCH_V7_ENDPOINT, where the code has it.
VECTOR_DB defaults to pgvector on the slim image.
ENABLE_LOCAL_WEB_FETCH is the current name of the SSRF gate and was missing. ENABLE_RAG_LOCAL_WEB_FETCH is kept as the deprecated alias the code still reads, and keeps its anchor. Both are startup settings, not persisted ones.
OAUTH_GROUP_CLAIM now notes that OAUTH_GROUPS_CLAIM is read too and takes precedence.

Persistence labels

Each entry also says whether the setting is persisted (a ConfigVar, stored in the database after first start and editable in the admin panel) or applied from the environment at every start. The authoritative list is the DEFAULT_CONFIG registry in config.py, which Config.seed_defaults loads. I compared every label against it:

25 entries are labeled persisted but are plain startup imports: LICENSE_KEY, SSL_ASSERT_FINGERPRINT, ENABLE_PUBLIC_ACTIVE_USERS_COUNT, ELEVENLABS_API_BASE_URL, ENABLE_ONEDRIVE_PERSONAL, ENABLE_ONEDRIVE_BUSINESS, all seven ELASTICSEARCH_*, five MILVUS_* and four PGVECTOR_* index settings, and the three SCIM settings.
8 persisted settings were labeled startup-only or not labeled: AUTOMATION_AUTH_TOKEN_EXPIRES_IN, the six prompt templates (TITLE_GENERATION_PROMPT_TEMPLATE, FOLLOW_UP_GENERATION_PROMPT_TEMPLATE, AUTOCOMPLETE_GENERATION_PROMPT_TEMPLATE, TAGS_GENERATION_PROMPT_TEMPLATE, QUERY_GENERATION_PROMPT_TEMPLATE, RAG_TEMPLATE) and OAUTH_AUDIENCE.
SCIM was documented twice, once inside the OAuth section under the current ENABLE_SCIM name and once in its own section under the old SCIM_ENABLED name, so the page had two SCIM_TOKEN and two SCIM_AUTH_PROVIDER headings. The SCIM section now holds the newer three entries (which already note the SCIM_ENABLED alias) and the copies in the OAuth section are gone.
IMAGES_OPENAI_API_PARAMS is the admin config key. The environment variable is IMAGES_OPENAI_PARAMS. The entry now says both.

Types and option lists

29 entries said str where the code casts the value to a boolean at assignment: 25 of the USER_PERMISSIONS_* flags, S3_USE_ACCELERATE_ENDPOINT, S3_ENABLE_TAGGING and PGVECTOR_CREATE_EXTENSION. PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH is an int.
WEB_SEARCH_ENGINE listed azure_ai_search. The value the backend matches is azure.
WEB_LOADER_ENGINE was missing microsoft_web_iq, which the loader accepts alongside the five listed values.
RAG_TEXT_SPLITTER was missing token_transformers, and both it and RAG_TOKENIZER_MODEL said the HuggingFace tokenizer applies to the token splitter. In the code token is Tiktoken only, and the tokenizer model is read by token_transformers.

None.

Checklist

I have reviewed the relevant documentation and matched the existing style.
This PR meets Open WebUI's contribution standards: it is accurate, relevant to users, narrowly scoped, maintainable, and not promotional content, advertising, lead generation, SEO placement, or a request to list a product, service, provider, integration, gateway, tool, or company primarily for visibility.
I understand that PRs that do not meet these standards may be closed without review and will not be merged. Repeated, low-quality, off-topic, promotional, or intentionally misleading submissions may result in the contributor being blocked from future participation in Open WebUI repositories.

Notes for reviewers

Every default was read from the os.getenv call in config.py or env.py at dev HEAD and again at the v0.11.3 tag, and the two agree on all of the above. The locale fallback comes from src/routes/+layout.svelte. Existing anchors are unchanged, so the links from the hardening guide and the SSO tutorials still resolve. For every relabeled persistence entry I checked both whether the name appears as a value in DEFAULT_CONFIG (directly, through the parsed JSON variable it feeds, or through the user permissions object) and whether the routers read it as app.state.config.NAME or import the module constant. The two agree in every case. Settings that feed a persisted list under another name (OPENAI_API_BASE_URL into openai.api_base_urls) keep their persisted label.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/open-webui/docs/pull/1395 **Author:** [@silentoplayz](https://github.com/silentoplayz) **Created:** 9/18/2026 **Status:** ✅ Merged **Merged:** 9/18/2026 **Merged by:** [@silentoplayz](https://github.com/silentoplayz) **Base:** `main` ← **Head:** `docs/env-defaults` --- ### 📝 Commits (5) - [`6ab08a8`](https://github.com/open-webui/docs/commit/6ab08a82bc91726846b3ff00105815df15b370ce) docs: correct env-reference defaults that drifted from config.py and env.py - [`8077917`](https://github.com/open-webui/docs/commit/8077917ab54ea312ebc764ba13b9369248e142bc) docs: the local web fetch gate is a startup setting, not a persisted one - [`934f3c3`](https://github.com/open-webui/docs/commit/934f3c3e6bece25db9bd6ba7847bdee39d5b56a1) docs: label persisted and startup-only settings the way config.py registers them - [`1c48d27`](https://github.com/open-webui/docs/commit/1c48d27459e95cb98e30f50ad9c94f25357be01a) docs: fix env-reference types, the Azure search value, and the splitter options against the code - [`70e49fe`](https://github.com/open-webui/docs/commit/70e49fece9ef1c52419a82ddc2630da43ea1c348) docs: use the variable names the code reads for Google Drive and the Playwright websocket ### 📊 Changes **1 file changed** (+123 additions, -123 deletions) <details> <summary>View changed files</summary> 📝 `docs/reference/env-configuration.mdx` (+123 -123) </details> ### 📄 Description ## Summary I compared every `- Default:` line in the environment variable reference against `backend/open_webui/config.py` and `backend/open_webui/env.py`, on `dev` and at the v0.11.3 tag. Most entries match. These did not, and each one below now states what the code does: - `ENABLE_DIRECT_CONNECTIONS` and `ENABLE_AUTOCOMPLETE_GENERATION` default to `False`, not `True`. - `RAG_EMBEDDING_MODEL_TRUST_REMOTE_CODE` and `RAG_RERANKING_MODEL_TRUST_REMOTE_CODE` default to `True`, not `False`. - `DATABASE_ENABLE_SQLITE_WAL` defaults to `True`, not `False`. - `ENABLE_IMAGE_EDIT` defaults to `False`, not `true`. - The four `USER_PERMISSIONS_WORKSPACE_{MODELS,PROMPTS}_{IMPORT,EXPORT}` flags default to `False`, not `True`, and are booleans. - `TIKA_SERVER_URL` defaults to `http://tika:9998`, not `http://localhost:9998`. - `DOCUMENT_INTELLIGENCE_MODEL` defaults to `prebuilt-layout`, not `None`. - `CODE_EXECUTION_JUPYTER_TIMEOUT` defaults to `60`, and the five `CODE_INTERPRETER_JUPYTER_*` settings fall back to their `CODE_EXECUTION_JUPYTER_*` counterparts, which the page did not say. - `PLAYWRIGHT_TIMEOUT` defaults to `10000` milliseconds, not empty. - `AIOHTTP_CLIENT_TIMEOUT` is unset by default, which means no timeout. `300` is only the fallback for a value that fails to parse. The page had the two the other way round. - `WEBUI_URL`, `DEFAULT_LOCALE` and `AUDIO_STT_MODEL` default to an empty string, not `http://localhost:3000`, `en` and `whisper-1`. For the locale the page now says what an empty value does (the browser's language, then `en-US`). - `BING_SEARCH_V7_SUBSCRIPTION_KEY` listed the endpoint URL as its default. The URL now sits on `BING_SEARCH_V7_ENDPOINT`, where the code has it. - `VECTOR_DB` defaults to `pgvector` on the slim image. - `ENABLE_LOCAL_WEB_FETCH` is the current name of the SSRF gate and was missing. `ENABLE_RAG_LOCAL_WEB_FETCH` is kept as the deprecated alias the code still reads, and keeps its anchor. Both are startup settings, not persisted ones. - `OAUTH_GROUP_CLAIM` now notes that `OAUTH_GROUPS_CLAIM` is read too and takes precedence. ### Persistence labels Each entry also says whether the setting is persisted (a `ConfigVar`, stored in the database after first start and editable in the admin panel) or applied from the environment at every start. The authoritative list is the `DEFAULT_CONFIG` registry in `config.py`, which `Config.seed_defaults` loads. I compared every label against it: - 25 entries are labeled persisted but are plain startup imports: `LICENSE_KEY`, `SSL_ASSERT_FINGERPRINT`, `ENABLE_PUBLIC_ACTIVE_USERS_COUNT`, `ELEVENLABS_API_BASE_URL`, `ENABLE_ONEDRIVE_PERSONAL`, `ENABLE_ONEDRIVE_BUSINESS`, all seven `ELASTICSEARCH_*`, five `MILVUS_*` and four `PGVECTOR_*` index settings, and the three SCIM settings. - 8 persisted settings were labeled startup-only or not labeled: `AUTOMATION_AUTH_TOKEN_EXPIRES_IN`, the six prompt templates (`TITLE_GENERATION_PROMPT_TEMPLATE`, `FOLLOW_UP_GENERATION_PROMPT_TEMPLATE`, `AUTOCOMPLETE_GENERATION_PROMPT_TEMPLATE`, `TAGS_GENERATION_PROMPT_TEMPLATE`, `QUERY_GENERATION_PROMPT_TEMPLATE`, `RAG_TEMPLATE`) and `OAUTH_AUDIENCE`. - SCIM was documented twice, once inside the OAuth section under the current `ENABLE_SCIM` name and once in its own section under the old `SCIM_ENABLED` name, so the page had two `SCIM_TOKEN` and two `SCIM_AUTH_PROVIDER` headings. The SCIM section now holds the newer three entries (which already note the `SCIM_ENABLED` alias) and the copies in the OAuth section are gone. - `IMAGES_OPENAI_API_PARAMS` is the admin config key. The environment variable is `IMAGES_OPENAI_PARAMS`. The entry now says both. ### Types and option lists - 29 entries said `str` where the code casts the value to a boolean at assignment: 25 of the `USER_PERMISSIONS_*` flags, `S3_USE_ACCELERATE_ENDPOINT`, `S3_ENABLE_TAGGING` and `PGVECTOR_CREATE_EXTENSION`. `PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH` is an `int`. - `WEB_SEARCH_ENGINE` listed `azure_ai_search`. The value the backend matches is `azure`. - `WEB_LOADER_ENGINE` was missing `microsoft_web_iq`, which the loader accepts alongside the five listed values. - `RAG_TEXT_SPLITTER` was missing `token_transformers`, and both it and `RAG_TOKENIZER_MODEL` said the HuggingFace tokenizer applies to the `token` splitter. In the code `token` is Tiktoken only, and the tokenizer model is read by `token_transformers`. ## Related issue or discussion None. ## Checklist - [x] I have reviewed the relevant documentation and matched the existing style. - [x] This PR meets Open WebUI's contribution standards: it is accurate, relevant to users, narrowly scoped, maintainable, and not promotional content, advertising, lead generation, SEO placement, or a request to list a product, service, provider, integration, gateway, tool, or company primarily for visibility. - [x] I understand that PRs that do not meet these standards may be closed without review and will not be merged. Repeated, low-quality, off-topic, promotional, or intentionally misleading submissions may result in the contributor being blocked from future participation in Open WebUI repositories. ## Notes for reviewers Every default was read from the `os.getenv` call in `config.py` or `env.py` at `dev` HEAD and again at the v0.11.3 tag, and the two agree on all of the above. The locale fallback comes from `src/routes/+layout.svelte`. Existing anchors are unchanged, so the links from the hardening guide and the SSO tutorials still resolve. For every relabeled persistence entry I checked both whether the name appears as a value in `DEFAULT_CONFIG` (directly, through the parsed JSON variable it feeds, or through the user permissions object) and whether the routers read it as `app.state.config.NAME` or import the module constant. The two agree in every case. Settings that feed a persisted list under another name (`OPENAI_API_BASE_URL` into `openai.api_base_urls`) keep their persisted label. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-18 14:19:07 +00:00