Immich Restore Guide 

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 GCS backup at gs://immich-backups-amar

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 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: Install and Configure Google Cloud CLI

1. Install Google Cloud CLI:

sudo apt-get updateCopy
sudo apt-get install apt-transport-https ca-certificates gnupg curlCopy
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpgCopy
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.listCopy
sudo apt-get update && sudo apt-get install google-cloud-cliCopy

2. Configure Google Cloud CLI:

gcloud initCopy
gcloud auth loginCopy
gcloud auth application-default loginCopy

3. Verify GCS Access:

gsutil ls gs://immich-backups-amarCopy

Step 5: 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:

Copy Allnano .env

# Update these values:
UPLOAD_LOCATION=/mnt/immich_data/upload
DB_DATA_LOCATION=/mnt/immich_data/db
TZ=Asia/Kolkata

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 6: 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. Wait for PostgreSQL to be ready:

sleep 10Copy

Step 7: Download the Database Backup from GCS

1. List available database backups:

gsutil ls gs://immich-backups-amar/Daily_Database_Backup/Copy

2. Download the desired database backup:

Copy All# Get the latest backup filename
LATEST_BACKUP=$(gsutil ls gs://immich-backups-amar/Daily_Database_Backup/immich_db_*.sql.gz | sort | tail -1)
echo "Downloading: $LATEST_BACKUP"

# Download the backup
gsutil cp "$LATEST_BACKUP" /tmp/immich_db_restore.sql.gz

Step 8: Restore the Database

1. Restore the database backup:

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

2. Verify the restore:

docker logs immich_postgresCopy

Step 9: Sync Asset Files from GCS

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

mkdir -p /mnt/immich_data/uploadCopy

2. Sync all folders from GCS:

Copy Allfor dir in backups library encoded-video thumbs upload profile; do
  echo "Syncing $dir..."
  mkdir -p /mnt/immich_data/upload/$dir
  gsutil -m rsync -r -d gs://immich-backups-amar/$dir/ /mnt/immich_data/upload/$dir/
done

3. Set proper permissions after sync:

sudo chown -R 999:999 /mnt/immich_data/uploadCopy
sudo chmod -R 755 /mnt/immich_data/uploadCopy

4. Verify the restored files:

ls -l /mnt/immich_data/uploadCopy

Step 10: Start the Remaining Immich Services

1. Start all Immich services:

docker compose up -dCopy

2. Verify all containers are running:

docker compose psCopy

Step 11: Verify the Restoration

1. Check the Immich web interface:

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

2. Check the logs:

docker logs immich_serverCopy
docker logs immich_microservicesCopy
docker logs immich_postgresCopy

3. Verify database connectivity:

docker exec -it immich_postgres psql -U postgres -d immich -c "SELECT COUNT(*) FROM users;"Copy

Step 12: Resume Backups

1. Copy your backup script to the server:

sudo nano /home/ubuntu/immich-app/immich_backup.shCopy

2. Make it executable:

sudo chmod +x /home/ubuntu/immich-app/immich_backup.shCopy

3. Set up cron job (daily at 2 AM):

Copy Allsudo crontab -e

4. Add this line::

Copy All0 2 * * * /home/ubuntu/immich-app/immich_backup.sh

Troubleshooting

Database Issues:

Copy All# If database restore fails, reset and try again
docker compose down
docker volume rm immich_pgdata
docker compose up -d database
sleep 10
# Then restore database again

Permission Issues:

Copy All# Fix permissions if containers can't access files
sudo chown -R 999:999 /mnt/immich_data/upload
sudo chown -R 1000:1000 /mnt/immich_data/db
sudo chmod -R 755 /mnt/immich_data/

GCS Authentication Issues:

# Re-authenticate if neededCopy
gcloud auth loginCopy
gcloud auth application-default loginCopy

Container Issues:

Copy All# Restart specific services
docker compose restart immich_server
docker compose restart immich_microservices

# View real-time logs
docker compose logs -f

Complete Automated Restore Script

Copy All
# Set proper permissions
sudo chown -R 999:999 "$DATA_DIR/upload"
sudo chmod -R 755 "$DATA_DIR"

# Start all services
echo "Starting all Immich services..."
docker compose up -d

# Cleanup
rm -f /tmp/immich_db_restore.sql.gz

echo "Restore completed successfully!"
echo "Access Immich at: http://$(hostname -I | awk '{print $1}'):2283"
echo "Check logs with: docker compose logs -f"

Make it executable and run:

chmod +x complete_restore.shCopy
./complete_restore.shCopy

This restore guide follows the proven working steps from your AWS example, adapted specifically for your Google Cloud Storage setup. The process ensures a complete restoration of your Immich instance with all photos, metadata, and configurations intact.