Immich Disaster Recover Guide for TrueNas Scale – “Common Mistakes and How to Avoid Them”

So while i was working on the article for the Immich Storage Layout migration, i accidently deleted the wrong instance of Immich …. nice .. NOT !

Prerequisites

As per Community Guidelines Backup and Restore | Immich you should have backed up the following items:

Database Dump
Backup of
- UPLOAD_LOCATION/library
- UPLOAD_LOCATION/upload
- UPLOAD_LOCATION/profile
Database Password

How to dump the database?

By default, Immich will keep the last 14 database dumps and create a new dump every day at 2:00 AM.

You are able to trigger a database dump in the admin job status page. Visit the page, open the “Create job” modal from the top right, select “Create Database Dump” and click “Confirm”. A job will run and trigger a dump, you can verify this worked correctly by checking the logs or the backups/ folder. This dumps will count towards the last X dumps that will be kept based on your settings.

truenas[~]$ ls -lisa /mnt/ssd-pool/immich/backup
total 5638077
 34     11 drwxrwx--- 2 root root        17 Sep 24 02:01 .
 34      2 drwxrwx--- 8 root root         8 Sep  8 15:11 ..
128 402792 -rwxrwx--- 1 root root 412190060 Sep 11 02:01 immich-db-backup-20250911T020000-v1.140.1-pg15.14.sql.gz
  4 402455 -rwxrwx--- 1 root root 411846061 Sep 12 02:01 immich-db-backup-20250912T020000-v1.140.1-pg15.14.sql.gz
  5 402461 -rwxrwx--- 1 root root 411852547 Sep 13 02:01 immich-db-backup-20250913T020000-v1.140.1-pg15.14.sql.gz
256 402502 -rwxrwx--- 1 root root 411894239 Sep 14 02:01 immich-db-backup-20250914T020000-v1.140.1-pg15.14.sql.gz
384 402580 -rwxrwx--- 1 root root 411972656 Sep 15 02:01 immich-db-backup-20250915T020000-v1.140.1-pg15.14.sql.gz
257 402578 -rwxrwx--- 1 root root 411971365 Sep 16 02:01 immich-db-backup-20250916T020000-v1.140.1-pg15.14.sql.gz

Backup your Assets

Immich stores two types of content in the filesystem: (a) original, unmodified assets (photos and videos), and (b) generated content. Its recommend backing up the entire contents of UPLOAD_LOCATION, but only the original content is critical, which is stored in the following folders:

UPLOAD_LOCATION/library
UPLOAD_LOCATION/upload
UPLOAD_LOCATION/profile

If you choose to back up only those folders, you will need to rerun the transcoding and thumbnail generation jobs for all assets after you restore from a backup.

I myself rsync to another vdev + another nas + aws cloud

The Rsync Task on the TrueNas Gui wont allow to configure local2local rsync so i’ve opened a Feature Request here: Rsync Task should allow local 2 local synchronisation ( Local Destination Target ) – Feature Requests – TrueNAS Community Forums

Instead i’ve created a Cron Job like this for each asset:

rsync -rv /mnt/WD16TB/Fotos-ImmichApp/data/library /mnt/WD8TB/BACKUP/Fotos --ignore-existing --info=progress2 --delete --stats > /home/truenas_admin/rsync-foto.log

As an alternative you can also setup a cloud sync task Cloud Sync Tasks | TrueNAS Documentation Hub

The Disaster Recovery

1.) Create the Datasets / Folder Structure for your new Immich Instance

Note: If you want to use your old / original Datasets,
just wipe of all the data. You may peform a snapshot before.

2.) Copy the backed-up assets into the corresponding folders

3.) Set up a new Immich Instance of the App

Note: Do not log into the App prior the restore!

4.) Postgres Database Restore

a.) Figure out the Container ID for Postgres and copy the Databasedump into a location the postgres container has access to

truenas[~]$ sudo docker ps | grep immich | awk '{print $1,$2}'
cd56e15e39b6 ghcr.io/immich-app/immich-server:v2.0.1
de7cd1a5a18f ghcr.io/immich-app/postgres:15-vectorchord0.4.3-pgvectors0.2.0
16b2634a74b8 valkey/valkey:8.1.4
0b30677cdd24 ghcr.io/immich-app/immich-machine-learning:v2.0.1

b.) Figure out the external path ( Source ) and internal mount path within the container ( Destination )

truenas[~]$ sudo docker inspect -f '{{ json .Mounts }}' de7cd1a5a18f | python -m json.tool
[
    {
        "Type": "bind",
        "Source": "/mnt/ssd-pool/immich/pgData",
        "Destination": "/var/lib/postgresql/data",
        "Mode": "",
        "RW": true,
        "Propagation": "rprivate"
    }
]

c.) Copy the SQL Dump to the external Path, gunzip and adjust the permissons

truenas[~]$ cp /mnt/WD8TB/BACKUP/immich-db-backup-20250925T020000-v1.143.0-pg15.14.sql.gz /mnt/ssd-pool/immich/pgData

truenas[~]$ sudo ls -l /mnt/ssd-pool/immich/pgData
-rwxr-x--- 1 root    root   413877772 Sep 25 08:49 immich-db-backup-20250925T020000-v1.143.0-pg15.14.sql.gz

truenas[~]$ sudo gunzip /mnt/ssd-pool/immich/pgData/immich-db-backup-20250925T020000-v1.143.0-pg15.14.sql.gz

truenas[~]$ sudo chown netdata:docker /mnt/ssd-pool/immich/pgData/immich-db-backup-20250925T020000-v1.143.0-pg15.14.sql

truenas[~]$ sudo ls -l /mnt/ssd-pool/immich/pgData/
-rwxr-x--- 1 netdata docker 1045575836 Sep 25 08:49 immich-db-backup-20250925T020000-v1.143.0-pg15.14.sql

d.) Restore SQL Dump via psql

truenas[~]$ sudo docker exec  ix-immich-pgvecto-1 psql --dbname=postgres --username=immich -f /var/lib/postgresql/data/immich-db-backup-20250925T020000-v1.143.0-pg15.14.sql

6.) Re-Start the Immich App

Potential Issues during restore and how to avoid them

1.) PSQL Error: File not found

truenas[/]$ sudo docker exec ix-immich-pgvecto-1 psql --dbname=postgres --username=immich -f /mnt/ssd-pool/immich/pgData/immich-db-backup-20251015T020000-v1.143.1-pg15.14.sql*
psql: error: immich-db-backup-20251015T020000-v1.143.1-pg15.14.sql: No such file or directory

The namespace /mnt/ssd-pool/immich/pgData/ is correct for the initial data transfer, but the mount path inside the container is needed here. See here

truenas[/]$ sudo docker exec ix-immich-pgvecto-1 psql –dbname=postgres –username=immich -f /var/lib/postgresql/data/immich-db-backup-20251015T020000-v1.143.1-pg15.14.sql

2.) Server Exited due to failed authentication

microservices worker error: PostgresError: password authentication failed for user "immich", stack: PostgresError: password authentication failed for user "immich

On the TrueNas Apps Page select your Immich Instance, then under Workloads click on the Shell prompt icon. You can then use immich-admin as needed:

3.) SQL Restore Error

truenas_admin@truenas[~]$ sudo docker exec ix-immich-restore-test-pgvecto-1 psql --dbname=postgres --username=immich -f /var/lib/postgresql/data/immich-db-backup-20250925T020000-v1.143.0-pg15.14.sql
SET
SET
SET
DROP DATABASE
psql:/var/lib/postgresql/data/immich-db-backup-20250925T020000-v1.143.0-pg15.14.sql:25: ERROR: current user cannot be dropped
psql:/var/lib/postgresql/data/immich-db-backup-20250925T020000-v1.143.0-pg15.14.sql:32: ERROR: role "immich" already exists

NOTE: Note that for the database restore to proceed properly, it requires a completely fresh install (i.e. the Immich server has never run since creating the Docker containers). If the Immich app has run, Postgres conflicts may be encountered upon database restoration (relation already exists, violated foreign key constraints, multiple primary keys, etc.), in which case you need to delete the DB_DATA_LOCATION folder to reset the database.

4.) ENOENT: no such file or directory, open ‘upload/encoded-video/.immich’

File does not exist - user restored from a backup, but did not restore each folder (user should restore all folders or manually create .immich in any missing folders) See: Immich System Integrity | Folder checks