Backup and Restore Immich from TrueNAS Scale to Docker using pg_dumpall

[ra7bi]

Backup and Restore Immich from TrueNAS Scale to Docker

This guide will walk you through the steps to backup your Immich database and relevant folders from a TrueNAS Scale environment and restore them to a Docker-based system.

Backup Immich Database and Folders from TrueNAS Scale

1. SSH into your TrueNAS Scale server:

   ssh <your_truenas_scale_server>

2. Get the PostgreSQL pod name:

   sudo k3s kubectl get pods -n ix-immich

   Look for the pod name that starts with immich-postgres.

3. Dump the PostgreSQL database:

   sudo k3s kubectl exec -it <immich-postgres-pod-name> -n ix-immich -- sh -c "pg_dumpall --clean --if-exists --username=immich" | gzip > /tmp/dump.sql.gz

4. Move the dump file to a desired location:

   mv /tmp/dump.sql.gz /home/xxxx

5. Copy the required folders:

   mkdir /home/xxxx/backupLibrary
   cp -r /path_to_library_folder /home/xxxx/backupLibrary/library
   cp -r /path_to_upload_folder /home/xxxx/backupLibrary/upload
   cp -r /path_to_profile_folder /home/xxxx/backupLibrary/profile

6. Download the dump file and backupLibrary folder to your local machine:

   Use scp or any other method to download the dump file and backupLibrary folder to your local machine.

Restore Immich Database and Folders on Docker

1. Copy the backupLibrary folder to your new Docker server:

   Use scp or any other method to upload the backupLibrary folder to your new Docker server.

2. Download and set up Immich on your Docker server:

   Follow the Immich Docker installation guide to download and set up Immich.

3. Update the UPLOAD_LOCATION in your .env file:

   Set the UPLOAD_LOCATION to point to the backupLibrary folder:

   UPLOAD_LOCATION=/path_to_backupLibrary

4. Check the PostgreSQL version in TrueNAS Scale:

   sudo k3s kubectl exec -it <immich-postgres-pod-name> -n ix-immich -- psql --username=immich -c "SELECT version();"

   Make sure the version matches with the PostgreSQL version in your Docker setup. If not, update your Docker YAML file to match the PostgreSQL version.

5. Prepare the dump file:

   sudo gunzip < "/path_to_your_local_copy/dump.sql.gz" \
   | sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" \
   | sudo docker exec -i immich_postgres psql --username=postgres

Notes

• Replace <immich-postgres-pod-name> with the actual PostgreSQL pod name obtained in step 2.
• Replace /home/xxxx with the actual path where you want to move the dump file.
• Replace /path_to_backupLibrary with the actual path to the backupLibrary folder on your Docker server.
• Ensure you have sed and gzip installed on your local machine for processing the dump file.

This guide should help you smoothly backup and restore your Immich database and relevant folders between TrueNAS Scale and any Docker-based system. If you encounter any issues, please refer to the relevant PostgreSQL and Docker documentation for further assistance.

Thanks you

[ramondsq]

Hello there.
My Truenas immich app broke when updating and could never start. I tried to use the postgres backup SQL files generated automatically by the Truenas immich app and follow your instructions to restore in my local docker. When I go though the step 5. Prepare the dump file. I would encounter the ERROR: role "immich" does not exist and could not get my previous configs restored. I'd like to know how can I solve this.

[ra7bi]

In PostgreSQL, roles are used to manage permissions and access control to the database.
regarding the error "role 'immich' does not exist" during a backup restore, it means that PostgreSQL is trying to restore data for a user (role) named "immich," but that role hasn't been created in the target database.

So ig , before restoring the backup, you can create the missing role by running:
CREATE ROLE immich WITH LOGIN;
LOGIN => allows it to log in

[DarkLordGMS]

In PostgreSQL, roles are used to manage permissions and access control to the database. regarding the error "role 'immich' does not exist" during a backup restore, it means that PostgreSQL is trying to restore data for a user (role) named "immich," but that role hasn't been created in the target database.

So ig , before restoring the backup, you can create the missing role by running: CREATE ROLE immich WITH LOGIN; LOGIN => allows it to log in

But how do we run that?

[steve1123456]

Hey @ra7bi , thanks for this excellent guide!

There are a couple of steps that I'm a little unclear about, and I'm wondering if they're even required, given the way that I setup Immich initially (using 7 separate datasets via HostPaths per the community guide here.). Since my database is relatively easily accessible inside the pgData dataset (I can mount via SMB to copy it), do I have to do the steps of "dump"ing the database? Can I simply copy the library/upload/profile folders and put those 3 folders under UPLOAD_LOCATION=/path_to_backupLibrary, and then copy the pgData folder to DB_DATA_LOCATION=./postgres and update the .env file with these paths? Or would this not be sufficient?

Sorry, I'm just a little n00b with the command line and try to avoid it when I can lol.

[ra7bi]

The main point is how you can get the db backup and restore it. Some steps are not really necessary The main point is how you can get the db backup and restore it. Some steps are not really necessary .

Good luck 🤞

[steve1123456]

Thanks for the fast reply! Ok I think I follow. I suppose some steps are required if Immich was installed without datasets/HostPaths, and you have to "go into the postgres inner workings" so-to-speak to find and pullout the db, but since I installed mine by using datasets, I should be able to do a copy/paste from the pgData folder to it's new home on the Proxmox LXC container under DB_DATA_LOCATION=./postgres, along with copying the 3 folders (library/upload/profile) inside the UPLOAD_LOCATION=/path, and be good to go? If I'm following correctly?
Thanks again! Appreciate your advice.

[ra7bi]

ig yes , the path in the DB for each folder should match the path where you placed your actual files .

[ericarthurc]

First off you are a life saver man.. this was what I needed to perform a migration from TrueNas Scale to Ubuntu Server docker compose.. I moved over my configuration and 320gbs of images (immich library).

A couple things have changed since this post though.. so here is some updates.

k3s is not on TrueNas Scale anymore.. you have to now use the docker comannd line.

So when you perform the backup of the postgres database use this:

docker exec -t immich_postgres pg_dumpall --clean --if-exists --username=immich | gzip > "/path/to/backup/dump.sql.gz"

Key side note about the command above. The offical backup and restore docs from immich will have the username as postgres but the Truenas version will use immich. So keep that in mind with that above command.

Also the part about the pod name is no longer needed if you are using docker. The command above assumes you are using immich_postgres for your docker container name, which is the default for TrueNas scale.

Once you get that backup sql.gz file, move that some where to your new ubuntu server. I used scp to move it over.. but whatever works. Mine was 180 mbs large.

On your ubuntu system, when you are first setting up your new docker compose file for the whole immich setup, you will need to make sure you are using the SAME version (docker image) for postgres. TrueNas Scale's docker file for immich uses postgres 15... the default docker compose file from the immich github is using version 14.. these have to be the same. Just manually adjust the compose.yml file and update the postgres image to whatever you need to match the TrueNas scale postgress immich image version.

In TrueNas Scale you will have 7 directories for your immich data... THIS IS IMPORTANT... grab them ALL! Then put all seven folders into a new parent folder and migrate them onto your new ubuntu system. In the new docker-compose.yml file on the new system.. point the UPLOAD_LOCATION environmental variable to that parent folder. It will use all seven folders inside that new parent folder for all the data and your previous data form the TrueNas system...

Make backups of everything if you can.. take your time.. and do NOT START the docker compose file yet..

Then you can actually follow the rest of the Restore docs on the offical webpage: https://immich.app/docs/administration/backup-and-restore/ .

From a clean setup (so never have ran the immich docker compose file yet), run:

docker compose pull    # this grabs all the images for the compose file
docker compose create   # this builds the containers without starting them
docker start immich_postgres    # this starts the postgres database and nothing else


# update the path/to/backup to were you actually have your .sql.gz backup file
# then run this command against your docker container and you will start to see a bunch of SQL statements processing in your terminal.. wait for it to finish
gunzip --stdout "/path/to/backup/dump.sql.gz" \
| sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" \
| docker exec -i immich_postgres psql --dbname=postgres --username=postgres 

# once the above command it done, you can start the other containers
docker compose up -d

This will start up immich and then navigate to the webui port with your server hostname/ip.. you should be greated with your login page and your previous credentials and previous users will all be there and ready to login. Just login and everything will be there like it never was migrated lol... if done right immich wont even really know a difference.

Hope this helps yall out.. This took me a couple trial and error runs to get correct.. so make backups and test it out a couple times.

Critical things to remember.. has to be the same postgres version.. make sure you create the postgres dump correctly.. move all 7 directories into a new parent folder for the env variable.

[willowbit]

Hi! Thanks so much for writing this up. I'm following your steps, but when I run the gunzip command, I get the following:

ERROR:  database "template1" does not exist
ERROR:  option "locale_provider" not recognized
LINE 1: ...late1 WITH TEMPLATE = template0 ENCODING = 'UTF8' LOCALE_PRO...
                                                             ^
ERROR:  database "template1" does not exist
\connect: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL:  database "template1" does not exist

If anyone has any idea of how to troubleshoot this, I would appreciate it. Will post if I find a solution.

[ericarthurc]

What is the exact command you are running?

This is all one command; the top line needs to point to where you have your backup .gz file.
The postygres defaults for the ubuntu docker compuser based setup is --dbname=postgres --username=postgres "

gunzip --stdout "/path/to/backup/dump.sql.gz" \
| sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" \
| docker exec -i immich_postgres psql --dbname=postgres --username=postgres 

Also please make sure your postgres version and image in docker compose is the same one you were using from the system setup you are migrating from.

[willowbit]

Okay, you're right, "locale_provider" is a postgres 15+ feature, so something with that went wrong. I am having trouble finding which image I was using on my truenas server. I know that it was running postgres 15.12.

[ericarthurc]

I can't remember off the top of my head, but there is a way to see the full docker compose file running on your trunas and you can see the exact image it is using for postgres.

[willowbit]

Ok, found it. It is listed for me under "Workloads" in the truenas apps interface. For me it was "docker.io/tensorchord/pgvecto-rs:pg15-v0.2.0" Thanks so much for the help!

[msegec]

This is a half baked backup solution. Who makes a backup for your personal memories and provides a below sub-par backup and restore functionality?

I am stuck on a half broken truenas scale box right now that immich is the only reason it's up...

[bo0tzz]

@msegec our documented backup approach for the default setup (https://immich.app/docs/administration/backup-and-restore/) has been serving people without issue. The TrueNas install is different and unofficial, and so might need adaptations on top of our provided guides.