diff --git a/docs/getting-started/env-configuration.md b/docs/getting-started/env-configuration.md index a9bb236..f121fb6 100644 --- a/docs/getting-started/env-configuration.md +++ b/docs/getting-started/env-configuration.md @@ -31,6 +31,8 @@ You can update the values of `PersistentConfig` environment variables directly f Please note that `PersistentConfig` environment variables are clearly marked as such in the documentation below, so you can be aware of how they will behave. +To disable `PersistentConfig` and have Open WebUI treat all variables equally, you can set `ENABLE_PERSISTENT_CONFIG` to `False`. + ::: ## App/Backend @@ -46,9 +48,21 @@ environment variables, see our [logging documentation](https://docs.openwebui.co - Type: `str` - Default: `http://localhost:3000` -- Description: Specifies the URL where the Open WebUI is reachable. Currently used for search engine support. +- Description: Specifies the URL where your Open WebUI installation is reachable. Needed for search engine support and OAuth/SSO. - Persistence: This environment variable is a `PersistentConfig` variable. +:::warning + +This variable has to be set before you start using OAuth/SSO for authentication. +Since this is a persistent config environment variable, you can only change it through one of the following options: + + - Temporarily disabling persistent config using `ENABLE_PERSISTENT_CONFIG` + - Changing `WEBUI_URL` in the admin panel > settings and changing "WebUI URL". + +Failure to set WEBUI_URL before using OAuth/SSO will result in failure to log in. + +::: + #### `ENABLE_SIGNUP` - Type: `bool` @@ -152,7 +166,7 @@ is also being used and set to `True`. Failure to do so will result in the inabil - Type: `int` - Default: `0` -- Description: Sets the thread pool size for FastAPI/AnyIO blocking calls. By default (when set to 0) FastAPI/AnyIO use `40` threads. In case of large instances and many concurrent users, it may be needed to increase `THREAD_POOL_SIZE` to prevent blocking. +- Description: Sets the thread pool size for FastAPI/AnyIO blocking calls. By default (when set to `0`) FastAPI/AnyIO use `40` threads. In case of large instances and many concurrent users, it may be needed to increase `THREAD_POOL_SIZE` to prevent blocking. #### `SHOW_ADMIN_DETAILS` @@ -903,7 +917,7 @@ directly. Ensure that no users are present in the database if you intend to turn :::info -When deploying Open-WebUI in a multiple-node cluster with a load balancer, you must ensure that the WEBUI_SECRET_KEY value is the same across all instances in order to enable users to continue working if a node is recycled or their session is transferred to a different node. Without it, they will need to sign in again each time the underlying node changes. +When deploying Open-WebUI in a multi-node/worker cluster with a load balancer, you must ensure that the WEBUI_SECRET_KEY value is the same across all instances in order to enable users to continue working if a node is recycled or their session is transferred to a different node. Without it, they will need to sign in again each time the underlying node changes. ::: @@ -2479,6 +2493,12 @@ address. This is considered unsafe as not all OAuth providers will verify email - Description: If enabled, updates the local user profile picture with the OAuth-provided picture on login. - Persistence: This environment variable is a `PersistentConfig` variable. +::info + +If the OAuth picture claim is disabled by setting `OAUTH_PICTURE_CLAIM` to `''` (empty string), then setting this variable to `true` will not update the user profile pictures. + +::: + #### `WEBUI_AUTH_TRUSTED_EMAIL_HEADER` - Type: `str` @@ -2655,6 +2675,12 @@ See https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-o - Description: Set picture (avatar) claim for OpenID. - Persistence: This environment variable is a `PersistentConfig` variable. +::info + +If `OAUTH_PICTURE_CLAIM` is set to `''` (empty string), then the OAuth picture claim is disabled and the user profile pictures will not be saved. + +::: + #### `OAUTH_GROUP_CLAIM` - Type: `str` @@ -3136,7 +3162,7 @@ More information about this setting can be found [here](https://docs.sqlalchemy. :::info -When deploying Open-WebUI in a multi-node/worker cluster, you must ensure that the REDIS_URL value is set. Without it, session, persistency and consistency issues in the app-state will occur as the workers would be unable to communicate. +When deploying Open-WebUI in a multi-node/worker cluster with a load balancer, you must ensure that the REDIS_URL value is set. Without it, session, persistency and consistency issues in the app-state will occur as the workers would be unable to communicate. ::: @@ -3159,7 +3185,7 @@ When deploying Open-WebUI in a multi-node/worker cluster, you must ensure that t :::info -When deploying Open-WebUI in a multi-node/worker cluster, you must ensure that the ENABLE_WEBSOCKET_SUPPORT value is set. Without it, websocket consistency and persistency issues will occur. +When deploying Open-WebUI in a multi-node/worker cluster with a load balancer, you must ensure that the ENABLE_WEBSOCKET_SUPPORT value is set. Without it, websocket consistency and persistency issues will occur. ::: @@ -3171,7 +3197,7 @@ When deploying Open-WebUI in a multi-node/worker cluster, you must ensure that t :::info -When deploying Open-WebUI in a multi-node/worker cluster, you must ensure that the WEBSOCKET_MANAGER value is set and a key-value NoSQL database like Redis is used. Without it, websocket consistency and persistency issues will occur. +When deploying Open-WebUI in a multi-node/worker cluster with a load balancer, you must ensure that the WEBSOCKET_MANAGER value is set and a key-value NoSQL database like Redis is used. Without it, websocket consistency and persistency issues will occur. ::: @@ -3183,7 +3209,7 @@ When deploying Open-WebUI in a multi-node/worker cluster, you must ensure that t :::info -When deploying Open-WebUI in a multi-node/worker cluster, you must ensure that the WEBSOCKET_REDIS_URL value is set and a key-value NoSQL database like Redis is used. Without it, websocket consistency and persistency issues will occur. +When deploying Open-WebUI in a multi-node/worker cluster with a load balancer, you must ensure that the WEBSOCKET_REDIS_URL value is set and a key-value NoSQL database like Redis is used. Without it, websocket consistency and persistency issues will occur. :::