mirror of https://github.com/immich-app/immich.git synced 2025-04-24 13:16:41 +02:00

Matthew Momjian e1f8e96e28

* Update backup-and-restore.md

* Update template-backup-script.md

* Update FAQ.mdx

2024-04-06 09:05:00 -05:00

7.2 KiB

Raw Blame History

Backup and Restore

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

A 3-2-1 backup strategy is recommended to protect your data. You should keep copies of your uploaded photos/videos as well as the Immich database for a comprehensive backup solution. This page provides an overview on how to backup the database and the location of user-uploaded pictures and videos. A template bash script that can be run as a cron job is provided here

Database

:::caution Immich saves file paths in the database, it does not scan the library folder to update the database so backups are crucial. :::

:::info Refer to the official postgres documentation for details about backing up and restoring a postgres database. :::

The recommended way to backup and restore the Immich database is to use the pg_dumpall command.

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

docker compose down -v  # CAUTION! Deletes all Immich data to start from scratch.
docker compose pull     # Update to latest version of Immich (if desired)
docker compose create   # Create Docker containers for Immich apps without running them.
docker start immich_postgres    # Start Postgres server
sleep 10    # Wait for Postgres server to start up
gunzip < "/path/to/backup/dump.sql.gz" | docker exec -i immich_postgres psql --username=postgres    # Restore Backup
docker compose up -d    # Start remainder of Immich apps

docker exec -t immich_postgres pg_dumpall --clean --if-exists --username=postgres > "\path\to\backup\dump.sql"

docker compose down -v  # CAUTION! Deletes all Immich data to start from scratch.
docker compose pull     # Update to latest version of Immich (if desired)
docker compose create   # Create Docker containers for Immich apps without running them.
docker start immich_postgres    # Start Postgres server
sleep 10    # Wait for Postgres server to start up
gc "C:\path\to\backup\dump.sql" | docker exec -i immich_postgres psql --username=postgres    # Restore Backup
docker compose up -d    # Start remainder of Immich apps

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.).

The database dumps can also be automated (using this image) by editing the docker compose file to match the following:

services:
  ...
  backup:
    container_name: immich_db_dumper
    image: prodrigestivill/postgres-backup-local
    env_file:
      - .env
    environment:
      POSTGRES_HOST: database
      POSTGRES_CLUSTER: 'TRUE'
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      SCHEDULE: "@daily"
      POSTGRES_EXTRA_OPTS: '--clean --if-exists'
      BACKUP_DIR: /db_dumps
    volumes:
      - ./db_dumps:/db_dumps
    depends_on:
      - database

Then you can restore with the same command but pointed at the latest dump.

gunzip < db_dumps/last/immich-latest.sql.gz | docker exec -i immich_postgres psql --username=postgres

Filesystem

Immich stores two types of content in the filesystem: (1) original, unmodified content, and (2) generated content. Only the original content needs to be backed-up, which includes the following folders:

UPLOAD_LOCATION/library
UPLOAD_LOCATION/upload
UPLOAD_LOCATION/profile

Asset Types and Storage Locations

Some storage locations are impacted by the Storage Template. See below for more details.

:::note UPLOAD_LOCATION/library folder is not used by default on new machines running version 1.92.0. These are if the system administrator activated the storage template engine, for more info. :::

1. User-Specific Folders:

Each user has a unique string representing them.
You can find your user ID in Account Account Settings -> Account -> User ID.

2. Asset Types and Storage Locations:

Source Assets:
- Original assets uploaded through the browser interface & mobile & CLI.
- Stored in /library/upload/<userID>.
Avatar Images:
- User profile images.
- Stored in /library/profile/<userID>.
Thumbs Images:
- Preview images (blurred, small, large) for each asset and thumbnails for recognized faces.
- Stored in /library/thumbs/<userID>.
Encoded Assets:
- By default, unless otherwise specified re-encoded video assets for wider compatibility.
- Stored in /library/encoded-video/<userID>.

:::note If you choose to activate the storage template engine, it will move all assets to UPLOAD_LOCATION/library/<userID>.

When you turn off the storage template engine, it will leave the assets in UPLOAD_LOCATION/library/<userID> and will not return them to /library/upload.
New assets will be saved to /library/upload. :::