From cc679305ce2f95d542605df259f8b9ea73923538 Mon Sep 17 00:00:00 2001 From: spelingbee Date: Fri, 4 Sep 2026 15:39:23 +0600 Subject: [PATCH] docs: backups page says what cache/ is, and gains a Restoring section ## Summary Two additions to the backups page. The files table now says what `cache/` is (downloaded embedding and speech models, re-downloaded on demand, safe to exclude, and why two of the three example scripts exclude it: on a fresh instance it was 1.1 GB against about a megabyte of user data, and it contains symlinks). And a short Restoring section, since the page covers taking a backup and stops there: stop the stack, put the data directory back, start it, and make sure `webui.db-wal` / `webui.db-shm` travel with `webui.db` if files were copied individually. ## Related issue or discussion #1378 ## 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 Measured on v0.11.1 with the default SQLite setup, one account and one chat: `du` of the data directory was 1.1G, of which `cache/` was 1.1G, `webui.db` 632K, `webui.db-wal` 160K, `vector_db` 184K. The restore sequence was tested by restoring the directory into a fresh stack, with and without `cache/`. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_0193orVXP78niTTs6AzLThHK --- docs/tutorials/maintenance/backups.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/tutorials/maintenance/backups.md b/docs/tutorials/maintenance/backups.md index 833d7d3094..f7b88cab20 100644 --- a/docs/tutorials/maintenance/backups.md +++ b/docs/tutorials/maintenance/backups.md @@ -90,7 +90,7 @@ However your instance is provisioned, it's worth inspecting the app's data store | File/Directory | Description | |---|---| | `audit.log` | Log file for auditing events. | -| `cache/` | Directory for storing cached data. | +| `cache/` | Downloaded models for embeddings and speech (a Hugging Face cache). Re-downloaded on demand, so safe to exclude from backups; on a fresh instance it is already larger than everything else here put together, and it contains symlinks. Two of the three example scripts below exclude it. | | `uploads/` | Directory for storing user-uploaded files. | | `vector_db/` | Directory containing the ChromaDB vector database. | | `webui.db` | SQLite database for persistent storage of other instance data | @@ -398,6 +398,22 @@ This backup plan is a little more complicated but also more comprehensive .. it | Daily Incremental | Cloud Storage (B2) | rsync | Daily incremental backup pushed to a Backblaze B2 cloud storage bucket. | | Weekly Incremental | On-site Storage (Home NAS) | rsync | Weekly incremental backup pulled from the server to on-site storage (e.g., a home NAS). | +# Restoring + +Restoring is the mirror of the backup: stop the stack, put the data directory back, start the stack. + +```bash +docker compose down +# replace the contents of the persistent data directory (the volume, or the +# host path you bound) with the backup, keeping the same ownership +docker compose up -d +``` + +Two things to check before starting it again: + +- if you copied files individually rather than the whole directory, `webui.db-wal` and `webui.db-shm` have to come with `webui.db`, or the newest writes are missing; a copy taken with SQLite's `.backup` command does not have this problem; +- `cache/` does not need to be restored - Open WebUI downloads the models again on first use. + # Additional Topics In the interest of keeping this guide reasonably thorough these additional subjects were ommitted but may be worth your consideration depending upon how much time you have to dedicate to setting up and maintaining a data protection plan for your instance: