Docs: link Backup & Restore from the deploy pages, and name the -wal in "What to back up"

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

Nobody has claimed this yet.

Assessment

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

Research direction

Start with the Docker and Docker Compose deployment pages referenced in the issue and review their current persistent-storage and backup guidance. Document backing up the whole /var/opt/memos directory, including SQLite -wal and -shm handling, and explain stopping Memos before restore; done means the pages clearly describe both backup and restore steps.

Written by the indexing model from the issue text.

Description

Check before submitting
  • I searched existing issues and did not find a duplicate

Environment

What the documentation says

The deployment pages say to "keep your data directory on persistent storage" and to
"back up both the database and any local assets if you do not use database-backed
attachments". There is no backup page and no restore procedure, so that sentence is the
guidance a person acts on.

What I did

  1. Started Memos with the documented compose file.

  2. Created the host account and one memo through the API.

  3. Looked at the data directory:

    -rw-r--r--  4096    memos_prod.db
    -rw-r--r--  32768   memos_prod.db-shm
    -rw-r--r--  160712  memos_prod.db-wal
    
  4. Copied memos_prod.db - "the database" - and restored it into a fresh instance.

What I observed

Memos starts, /healthz answers 200, PRAGMA integrity_check returns ok, and the
instance is empty: no accounts, no memos, and the first-run screen asking for a new host
account. Copying the whole directory instead (all three files) restores everything
correctly.

Why this is worth a documentation change

memos_prod.db is the file whose name matches the phrase "the database", and on a
running instance almost nothing is in it - the writes are in -wal until a checkpoint.
The failure is silent in both directions: the backup looks fine (a valid SQLite file)
and the restore looks fine (a healthy, empty Memos). Nothing warns the person that they
have lost anything.

Suggested change

A short Backup and restore page, or one sentence on the Docker and Docker Compose
pages:

Back up the whole /var/opt/memos directory. If you copy the SQLite database on its
own, copy memos_prod.db-wal and memos_prod.db-shm with it, or stop Memos first -
otherwise the copy will be missing everything written since the last checkpoint.

Adding the reverse direction - "to restore, stop Memos, replace the directory, start it
again" - would round it out; there is no restore documentation at the moment.

I am happy to open a docs PR with that page if it would be welcome. Thank you for
Memos - the deployment story is otherwise about as simple as self-hosting gets.

Memos version: 0.30.0 (neosmemo/memos:0.30.0)


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

Dominant language
Go
Stars
63.2k
Forks
4.8k
Avg merge
20h 52m
Merged PRs (30d)
50

Contributor guide

No contributing guide indexed for this repository

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.

More from usememos/memos

All issues in usememos/memos

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.