From ad3f58bcda552180367791632b6ec59913a35d2f Mon Sep 17 00:00:00 2001 From: bo0tzz Date: Sat, 31 May 2025 22:10:14 +0200 Subject: [PATCH] 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> --- docs/docs/administration/backup-and-restore.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/docs/administration/backup-and-restore.md b/docs/docs/administration/backup-and-restore.md index 7e55e4e88ff..7b90c3b19ab 100644 --- 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.