chore: document backup ordering (#18807)

* chore: document backup ordering * chore: fix formatting --------- Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
2025-12-06 00:20:20 +01:00 · 2025-05-31 22:10:14 +02:00 · 2025-05-31 22:10:14 +02:00 · ad3f58bcda
commit ad3f58bcda
parent 0711a9006f
1 changed files with 7 additions and 0 deletions
--- a/docs/docs/administration/backup-and-restore.md
+++ b/docs/docs/administration/backup-and-restore.md
@ -219,3 +219,10 @@ When you turn off the storage template engine, it will leave the assets in `UPLO
 Do not touch the files inside these folders under any circumstances except taking a backup. Changing or removing an asset can cause untracked and missing files.
 You can think of it as App-Which-Must-Not-Be-Named, the only access to viewing, changing and deleting assets is only through the mobile or browser interface.
 :::
+
+## Backup ordering
+
+A backup of Immich should contain both the database and the asset files. When backing these up it's possible for them to get out of sync, potentially resulting in broken assets after you restore.  
+The best way of dealing with this is to stop the immich-server container while you take a backup. If nothing is changing then the backup will always be in sync.
+
+If stopping the container is not an option, then the recommended order is to back up the database first, and the filesystem second. This way, the worst case scenario is that there are files on the filesystem that the database doesn't know about. If necessary, these can be (re)uploaded manually after a restore. If the backup is done the other way around, with the filesystem first and the database second, it's possible for the restored database to reference files that aren't in the filesystem backup, thus resulting in broken assets.