From 9d613dbfa90c1b078fc38661728ade1b830e3c8b Mon Sep 17 00:00:00 2001 From: silentoplayz Date: Fri, 18 Sep 2026 13:41:38 -0400 Subject: [PATCH] docs: correct the S3, database migration and offline mode tutorials against the storage provider and env code --- docs/tutorials/maintenance/database.mdx | 2 +- docs/tutorials/maintenance/offline-mode.mdx | 2 +- docs/tutorials/maintenance/s3-storage.md | 15 ++++++++------- 3 files changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/tutorials/maintenance/database.mdx b/docs/tutorials/maintenance/database.mdx index 7b322df633..ec2dfaec09 100644 --- a/docs/tutorials/maintenance/database.mdx +++ b/docs/tutorials/maintenance/database.mdx @@ -3,7 +3,7 @@ sidebar_position: 310 title: "Exporting & Importing DB" --- -If you need to migrate your **Open WebUI** data (e.g., chat histories, configurations, etc.) from one server to another or back it up for later use, you can export and import the database. This guide assumes you're running Open WebUI using the internal SQLite database (not PostgreSQL). +If you need to migrate your **Open WebUI** data (e.g., chat histories, configurations, etc.) from one server to another or back it up for later use, you can export and import the database. This guide assumes you're running Open WebUI using the internal SQLite database (not PostgreSQL). Copying `webui.db` moves everything stored in the database (accounts, chats, settings, file and knowledge records) but not the files themselves: uploaded files under `/app/backend/data/uploads` and the vector store under `/app/backend/data/vector_db` stay behind, so chats that reference files will point at missing objects. Copy the whole `/app/backend/data` directory (see the [backups guide](/tutorials/maintenance/backups)) and keep the same `WEBUI_SECRET_KEY` for a complete move; the Docker image writes its auto-generated key to `/app/backend/.webui_secret_key`, outside that directory. With an external vector database such as PGVector, the vectors live there instead of in `vector_db`. Follow the steps below to export and import the `webui.db` file, which contains your database. diff --git a/docs/tutorials/maintenance/offline-mode.mdx b/docs/tutorials/maintenance/offline-mode.mdx index 8aa2f6c002..ee2395a93e 100644 --- a/docs/tutorials/maintenance/offline-mode.mdx +++ b/docs/tutorials/maintenance/offline-mode.mdx @@ -95,7 +95,7 @@ RAG_RERANKING_MODEL_AUTO_UPDATE=false WHISPER_MODEL_AUTO_UPDATE=false ``` -`OFFLINE_MODE` disables version checks and automatic model updates/downloads covered by that setting. `HF_HUB_OFFLINE` prevents Hugging Face Hub downloads. The three explicit model-update flags document that those caches should not update automatically. See the [offline configuration reference](/reference/env-configuration#offline_mode) for the full behavior. +`OFFLINE_MODE=true` on its own sets `HF_HUB_OFFLINE=1`, disables the version check and forces all three `*_AUTO_UPDATE` flags to false, so the four extra lines are redundant but harmless; `ENABLE_VERSION_UPDATE_CHECK=false` is the standalone switch for the version check alone. `WHISPER_MODEL_AUTO_UPDATE=false` does not by itself stop a download: if the Whisper model is missing from the cache, Open WebUI retries with downloads enabled, and only `HF_HUB_OFFLINE=1` blocks that attempt, which is why the cache must be prepared first. See the [offline configuration reference](/reference/env-configuration#offline_mode) for the full behavior. :::warning Prepare caches before enabling offline settings diff --git a/docs/tutorials/maintenance/s3-storage.md b/docs/tutorials/maintenance/s3-storage.md index 55dfa1a94d..e5ca51d7cf 100644 --- a/docs/tutorials/maintenance/s3-storage.md +++ b/docs/tutorials/maintenance/s3-storage.md @@ -18,7 +18,7 @@ This guide provides instructions on how to switch the default `local` storage in In order to follow this tutorial, you must have the following: - An active AWS account -- An active AWS Access Key and Secret Key +- An AWS Access Key and Secret Key, or another credential the default AWS credential chain can find (an IAM role, for example) - IAM permissions in AWS to create and put objects in S3 - Docker installed on your system @@ -32,9 +32,9 @@ To learn more about S3, visit: [Amazon S3's Official Page](https://aws.amazon.co # How to Set-Up -## 1. Required environment variables +## 1. S3 environment variables -In order to configure this option, you need to gather the following environment variables: +In order to configure this option, gather the following environment variables (only `S3_BUCKET_NAME` is strictly required; see Step 2): | **Open-WebUI Environment Variable** | **Example Value** | |-------------------------------------|---------------------------------------------| @@ -56,15 +56,16 @@ See all the `Cloud Storage` configuration options in the [Open-WebUI Cloud Stora ## 2. Run Open-WebUI -Before we launch our instance of Open-WebUI, there is one final environment variable called `STORAGE_PROVIDER` we need to set. This variable tells Open-WebUI which provider you want to use. By default, `STORAGE_PROVIDER` is empty which means Open-WebUI uses local storage. +Before we launch our instance of Open-WebUI, there is one final environment variable called `STORAGE_PROVIDER` we need to set. This variable tells Open-WebUI which provider you want to use. By default, `STORAGE_PROVIDER` is `local`; an empty or unknown value stops startup with "Unsupported storage provider". With `s3`, every upload is first written to `/app/backend/data/uploads` and then copied to the bucket, and each read downloads the object back there, so the local data volume is still needed. | **Storage Provider** | **Type** | **Description** | **Default** | |----------------------|----------|-------------------------------------------------------------------------------------------------|-------------| -| `local` | str | Defaults to local storage if an empty string (`' '`) is provided | Yes | +| `local` | str | Files stay under `/app/backend/data/uploads` | Yes | | `s3` | str | Uses S3 client library and related environment variables mentioned in Amazon S3 Storage | No | | `gcs` | str | Uses GCS client library and related environment variables mentioned in Google Cloud Storage | No | +| `azure` | str | Uses the Azure Blob Storage client with `AZURE_STORAGE_ENDPOINT` and `AZURE_STORAGE_CONTAINER_NAME`, plus `AZURE_STORAGE_KEY` or, without it, the default Azure credential | No | -To use Amazon S3, we need to set `STORAGE_PROVIDER` to "S3" along with all the environment variables we gathered in Step 1 (`S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_ENDPOINT_URL`, `S3_REGION_NAME`, `S3_BUCKET_NAME`). +To use Amazon S3, we need to set `STORAGE_PROVIDER` to `s3` (lowercase; the value is matched exactly) along with the environment variables we gathered in Step 1. Only `S3_BUCKET_NAME` is strictly required, with `S3_REGION_NAME` normally needed too: without `S3_ACCESS_KEY_ID` and `S3_SECRET_ACCESS_KEY` the default AWS credential chain (an IAM role, for example) is used, and `S3_ENDPOINT_URL` is only needed for S3-compatible services. `S3_KEY_PREFIX`, `S3_ADDRESSING_STYLE` (`path` for MinIO-style endpoints), `S3_USE_ACCELERATE_ENDPOINT` and `S3_ENABLE_TAGGING` are also available. Here, I'm also setting the `ENV` to "dev", which will allow us to see the Open-WebUI Swagger docs so we can further test and confirm the S3 storage set-up is working as expected. @@ -93,7 +94,7 @@ And confirm that we're getting a response from the selected LLM. ![Get a response in Open-WebUI](/images/tutorials/amazon-s3/amazon-s3-oui-response.png) -Great! Looks like everything is worked as expected in Open-WebUI. Now let's verify that the text file was indeed uploaded and stored in the specified S3 bucket. Using the AWS Management Console, we can see that there is now a file in the S3 bucket. In addition to the name of the file we uploaded (`hello.txt`) you can see the object's name was appended with a unique ID. This is how Open-WebUI tracks all the files uploaded. +Great! Looks like everything is worked as expected in Open-WebUI. Now let's verify that the text file was indeed uploaded and stored in the specified S3 bucket. Using the AWS Management Console, we can see that there is now a file in the S3 bucket. In addition to the name of the file we uploaded (`hello.txt`) you can see the object's name was prefixed with a unique ID (`_hello.txt`, under `S3_KEY_PREFIX` if set). This is how Open-WebUI tracks all the files uploaded. ![Get a response in Open-WebUI](/images/tutorials/amazon-s3/amazon-s3-object-in-bucket.png)