open-webui / open-webui/docs

Docs: the backups page lists cache/ as data to back up - on a fresh instance it is 99.9% of the backup

Open Beginner friendly
#1,378 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
875
Forks
630
Avg merge
15h 43m
Merged PRs (30d)
43

Description

Environment

What I did

Started a fresh instance, signed up one account, saved one chat, stopped the stack as
the page's scripts do, and copied /app/backend/data.

What I observed

1.1G    data
   0    data/uploads
 32K    data/webui.db-shm
160K    data/webui.db-wal
184K    data/vector_db
632K    data/webui.db
1.1G    data/cache

cache/ is a Hugging Face hub tree - all-MiniLM-L6-v2 and faster-whisper-base -
downloaded on first start. The page lists cache/ among the five things the data store
contains, next to webui.db and uploads/, with no note that it is regenerable. A
person following the page keeps 1.1 GB per snapshot for what is, at that moment, about
a megabyte of their own data.

Two smaller things from the same run, in case they are useful:

  1. The cache contains symlinks - 46 of them in my copy, from snapshots/ into
    blobs/. Any restore path that cannot create symlinks (a different operating system,
    a filesystem without them, some archive tooling) will not reproduce the tree. Excluding
    cache/ makes this go away as well.

  2. There is no restore procedure on the page. It covers taking the backup
    thoroughly and stops there. A person restoring for the first time is doing it on the
    worst day they have had this year, and the two things they need to be told are the
    order of operations and that webui.db-wal has to travel with webui.db - on my
    instance the -wal was 160 KiB against a 632 KiB database, so a copy of the .db
    alone would be missing the newest writes.

Suggested change

On the existing page, next to the list of five:

cache/ holds embedding and speech models that Open WebUI downloads on demand. It is
safe to exclude from backups - it will be re-downloaded - and on a fresh instance it is
already larger than everything else in this directory put together.

and a short Restoring section:

Stop the stack, replace /app/backend/data with the backup, and start it again. If
you copied files individually rather than the whole directory, make sure
webui.db-wal came with webui.db.

I would be glad to send a docs PR with both if that would be welcome. The backups page
is already one of the better ones in self-hosted software - it is the only project in a
set I have been testing that has a page about backups at all.


Everything above, with the commands and the unedited output, is at https://github.com/spelingbee/drillback/tree/main/docs/drill/open-webui - one leg of a restore drill across fifteen self-hosted applications, each one following its own backup documentation as written.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Open the existing maintenance/backups page referenced in the issue and review its current list of data-store contents and backup steps. Document that cache/ is regenerable, add the requested restoring section, and verify that the resulting instructions cover the full data directory and webui.db-wal.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, sqlite
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
88/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.