Immich Server Restore From S3 

Prerequisites

Before proceeding with the restoration process, ensure the following requirements are met, as this guide involves setting up a fresh Immich server:

• A freshly provisioned server running Ubuntu 22.04 LTS

• Root or sudo privileges to perform administrative tasks

• An active internet connection to download and install required packages

• An additional volume attached to the server (to store media files or database volumes)

• Basic familiarity with the Linux command-line interface (CLI)

• Access to your previously created S3 backup, as explained in the backup guide

Step 1: Prepare the System

Update your system to ensure all packages are up to date.

sudo apt update && sudo apt upgrade -yCopy

Step 2: Set Up the Volume

Format, mount, and configure the additional 150 GB volume to store Immich's data.

1. Identify the Extra Volume:

lsblkCopy

2. Format the Volume (Warning: This erases all data on the volume):

sudo mkfs.ext4 /dev/xvdbCopy

3. Create a Mount Point:

sudo mkdir /mnt/immich_dataCopy

4. Mount the Volume:

sudo mount /dev/xvdb /mnt/immich_dataCopy

5. Verify the Mount:

df -h /mnt/immich_dataCopy

6. Make the Mount Persistent by adding to /etc/fstab:

sudo blkid /dev/xvdbCopy
sudo nano /etc/fstabCopy

Add this line to /etc/fstab (replace UUID with your volume's UUID):

UUID=<your-uuid-here> /mnt/immich_data ext4 defaults,nofail 0 2Copy

7. Set Permissions:

sudo chown -R 1000:1000 /mnt/immich_dataCopy
sudo chmod -R 755 /mnt/immich_dataCopy

Step 3: Install Docker and Docker Compose

1. Add Docker's Official GPG Key:

sudo apt-get updateCopy
sudo apt-get install ca-certificates curlCopy
sudo install -m 0755 -d /etc/apt/keyringsCopy
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.ascCopy
sudo chmod a+r /etc/apt/keyrings/docker.ascCopy

2. Add the Repository to Apt Sources:

Copy Allecho \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

3. Install Docker and Docker Compose:

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-pluginCopy

Step 4: Set Up Immich

1. Create and navigate to Immich directory:

mkdir ./immich-appCopy
cd ./immich-appCopy

2. Download Docker Compose and .env files:

wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.ymlCopy
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.envCopy

3. Edit the .env file with key settings:

nano .envCopy

Copy
# Update these values:Copy
UPLOAD_LOCATION=/mnt/immich_data/uploadCopy
DB_DATA_LOCATION=/mnt/immich_data/dbCopy
TZ=Asia/KolkataCopy

4. Create directories and set permissions:

sudo mkdir -p /mnt/immich_data/upload /mnt/immich_data/dbCopy
sudo chown -R 1000:1000 /mnt/immich_dataCopy
sudo chmod -R 755 /mnt/immich_dataCopy

5. Pull Immich Image:

docker compose pullCopy

Step 5: Create the Docker containers without starting them

1. Create Immich Image:

docker compose createCopy

2. Start only the Postgres container:

docker start immich_postgresCopy

3. Start only the Postgres container:

sleep 10Copy

4. Install AWS CLI to Connect to S3

sudo apt updateCopy
sudo apt install awscliCopy

5. Configure AWS CLI with your credentials

aws configureCopy

Enter your AWS Access Key ID, Secret Access Key, region (e.g., ap-south-1), and output format (e.g., json).

Step 6: Download the Database Backup from S3

1. List available database backups: Run the following command to see the database backups in your S3 bucket (Change your bucket name accordingly)

aws s3 ls s3://immich-backups-aditya/Daily_Database_Backup/Copy

This will display files like immich_db_YYYYMMDD.sql.gz. Identify the backup you want to restore (e.g., the latest one).

2. Download the desired database backup: For example, to download immich_db_20250525.sql.gz:

aws s3 cp s3://immich-backups-aditya/Daily_Database_Backup/immich_db_20250525.sql.gz /tmp/immich_db_20250525.sql.gzCopy

Replace 20250525 with the date of the backup you want to restore

The file is downloaded to /tmp (you can choose another location)

Step 7: Restore the Database

1. Restore the database backup: Run the following command to decompress and restore the database:

Copy Allgunzip --stdout /tmp/immich_db_20250525.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

Replace /tmp/immich_db_20250525.sql.gz with the path to your downloaded backup file.

Replace postgres with your database username if it’s different.

The sed command adjusts the search path to avoid conflicts during restoration.

2. Verify the restore: Check the Postgres logs to ensure the restore was successful:

docker logs immich_postgresCopy

Look for any errors related to the restore process (e.g., "relation already exists" or "foreign key constraint violations"). If errors occur, ensure you started with a clean database.

Step 8: Sync Asset Files from S3

The backup script stored asset files in the S3 bucket under the folders backups, library, encoded-video, thumbs, upload, and profile. You need to restore these to the UPLOAD_LOCATION directory (e.g., /mnt/immich_data/upload).

1. Create the UPLOAD_LOCATION directory (if it doesn't exist):

mkdir -p /mnt/immich_data/uploadCopy

2. To sync all the folders (backups, library, encoded-video, thumbs, upload, profile) from the S3 bucket to the server in a single command, you can use a loop to iterate over the folders and sync them to the UPLOAD_LOCATION

for dir in backups library encoded-video thumbs upload profile; do aws s3 sync s3://immich-backups-aditya/$dir /mnt/immich_data/upload/$dir; doneCopy

3. Verify the restored files: Check that the folders and files exist in /mnt/immich_data/upload

ls -l /mnt/immich_data/uploadCopy

Step 9: Start the Remaining Immich Services

1. Start all Immich services

docker compose up -dCopy

2. Verify the Restoration

Check the Immich web interface: Open the Immich web interface (e.g., http://your-server:2283) and log in with your user credentials. Verify that your photos, videos, and metadata are intact.

docker logs immich_serverCopy
docker logs immich_microservicesCopy

This will Check the logs: Inspect the logs of the Immich containers for any errors:

Step 10: Resume Backups

Once the restoration is successful, resume your backup process by scheduling the provided script.sh as a cron job to ensure ongoing data protection. You can refer to the article Immich Server S3 Backup Guide