This guide covers what to back up, how to create a Kopia repository, an automated backup system with Web based GUI, a restore procedure, verification, scheduling, and retention. I’ve included comments/placeholder values you must replace for your environment.

---

Backup Immich with Kopia — Step-by-step guide

---

We will create a Kopia repository (local or S3), run a script that (1) produces a fresh Postgres dump and places it in UPLOAD_LOCATION/database-backup, (2) take a Kopia snapshot of your Immich upload folder and config files, and (3) use another script to delete the ephemeral database backup.

---

1) Prerequisites (check list)

Note: this is tested on Ubuntu 24.04. If you are running on another OS, you will have to change commands according to your OS

• Running Immich, know where your UPLOAD_LOCATION is (the folder holding photos, thumbnails, transcodes).
• Docker CLI access (to run docker exec for a live pg_dump).
• Enough disk/remote storage for your Kopia repository (local disk, S3/B2, rclone remote, etc.). Kopia supports many backends.

---

2) Decide what to snapshot

• Primary: UPLOAD_LOCATION (all original photos/videos + thumbnails/transcodes). Immich’s automatic DB dumps live in UPLOAD_LOCATION/backups by default (good). You should include the whole UPLOAD_LOCATION in snapshots. (Immich)
• Optional: Also snapshot: your Immich docker-compose.yml and .env (or the whole project folder), and any volumes root if you use bind mounts (so you can reconstruct container mounts).
• Optional: postgres data built in backups directory UPLOAD_LOCATION/backups is backup because we are creating backup with script while creating snapshot.
• Optional: thumbnails and transcodes are stored in UPLOAD_LOCATION/thumbs and UPLOAD_LOCATION/encoded-video. Backing up these are optional as these can be regenerated after restore but running jobs in immich admin panel.

---

3) Install Kopia

Official docs show installation methods per OS. Use the distribution’s package (APT), or download the binary. After install, run kopia --version to confirm. See Kopia install docs. (Kopia)

Note: Here it is assumed that we are using Kopia natively and not inside Docker.

---

4) Start Kopia server on boot (recommended)

We will use a systemd service to start Kopia on boot. Note: This is required for scheduled snapshots and maintenance to work.

Create

sudo nano /etc/systemd/system/kopia-server.service

and paste the following

[Unit]
Description=Kopia Repository Server
After=network.target

[Service]
Type=simple
User=root
Group=root
ExecStart=/usr/bin/kopia server start \
    --address=0.0.0.0:51515 \
    --insecure \
    --without-password
#   --server-control-username=admin \
#   --server-control-password=CHANGEME \
    --log-dir=/var/log/kopia
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

and run the following

sudo systemctl daemon-reload
sudo systemctl enable kopia-server
sudo systemctl start kopia-server

5) Create a Kopia repository

Choose where your backups will live (local disk, NAS, cloud-S3, etc). Every repository is encrypted via a password — keep it safe.

1. Open your browser and go to the Kopia Web UI: http://your-server-ip:51515 (or whichever address/port you configured).

2. In the left menu select “Repositories” (or simply “Repository” tab).

3. Click “+ New repository”

4. Choose your backend/storage type. Common options:

   • “Local directory / NAS” (for filesystem)
   • “S3 / S3-compatible”
   • “Azure Blob Storage”
   • “WebDAV / SFTP / Rclone”

5. Fill in the required fields:

   • For Local directory: a path (e.g., /backup/kopia-repo)
   • For S3: bucket name, access key, secret key, region, endpoint (if non-AWS)
   • For Azure / WebDAV / SFTP: follow the on-screen prompts

6. Enter a strong repository password (used for encryption) when prompted. This is essential — if you lose this password you cannot decrypt your backups.

7. (Optional) Click Advanced Options and review defaults for encryption algorithm, hash algorithm, splitter algorithm. Unless you know you need to change these, the defaults are fine.

8. Click Create or Save. Once created, the UI should confirm “Repository created” and show you the repository summary.

9. Back in Web UI you can now connect to (or use) this repository for creating snapshots etc.

10. We need to enable actions to allow scripts to run before and after snapshots. This which can only be done via terminal.

sudo kopia --enable-actions 

Then you’d connect to the repository and proceed.

Notes & tips

• Even though you create the repository via UI, the CLI is still useful for some advanced maintenance, debugging, user management (for server-mode) etc.
• Make sure your storage destination (disk, bucket, etc) is properly provisioned, has sufficient space, and is secured (permissions, network access, etc).
• Record the repository password and (if applicable) access credentials for the storage backend in a safe place (password manager, sealed envelope).

6) Database backup scripts

1. Download backup-database.sh and backup-database-del.sh from this repo.
2. Change DumpDir in both script to a folder inside UPLOAD_LOCATION.

Database backups will be made in this folder in this pattern: '2025-11-02_dump.sql'

7) Create a Snapshot Policy

Now that your repository is ready, you can use the UI to define what to back up and how often.

1. In your browser, in the left-menu choose “Snapshots” → “New Snapshot”

2. In the dialog:

   • For the Path, paste or type your upload folder /path/to/UPLOAD_LOCATION:

     e.g. /home/ubuntu/immich/library
     

3. Next, we will define “Policy”

   • In the UI you’ll find Scheduling — pick e.g. Every 12 h or Daily at Time of Day. It also supports full cron expressions. In this example, backups run at 23:00 every day.

• (Optional) In Files, make a rule to ignore thumbnails. In Ignore files, define

  /thumbs/*
  /encoded-video/*
  

• In Snapshot Actions → Before snapshot, select the path to backup-database.sh downloaded from this repo.
• In Snapshot Actions → After Snapshot select the path to backup-database-del.sh downloaded from this repo.

• (Optional) Set retention rules. Set sensible retention so snapshots don’t grow forever. Example: keep last 14 daily snapshots and 12 monthly snapshots.
• (Optional) Configure Compression, Exclude rules, etc., as needed.
• Click Snapshot Now to begin the backup process.

3. Kopia will schedule snapshots automatically based on that policy (provided the server/service is running).

   • Tip: You will still want to verify that scheduled snapshots are running (check in Tasks).
   • 1st backup will be slow but subsequent backups will be much faster because only changes will be transmitted.

---

8) Quick verify & inspect snapshots

Note: This is not supported in GUI.

• List snapshots for a source:

sudo kopia snapshot list --max-results 20

• Verify repository consistency (cheap) or verify file downloads (expensive):

sudo kopia snapshot verify --verify-files-percent=1      # verifies a percent of files; 100% to fully test

• Mount snapshot (read-only) with KopiaUI or kopia mount (useful to browse without restoring). See Kopia docs. (Kopia)

---

9) Restore procedure

TODO

10) Best practices & checklist

• Keep the Kopia repository encryption password in a secure secrets manager.
• Keep at least one offsite copy of the Kopia repository (e.g., S3 bucket, object storage, or replicate repository to another host).
• Test full restore end-to-end every few months (files + DB).
• Scan repository health with kopia snapshot verify --verify-files-percent=... occasionally. (Kopia)

11) FAQ

❓ Why Kopia and not Restic or Borg?

• Kopia is cross-platform and works on every major OS.
• It has an official built-in GUI.
• Multiple devices can backup to a single repository and benefit from deduplication and compression.
• E.g. — a Windows laptop and Immich instance can be backed up to same repo and photos on both devices will be deduplicated.

---

❓ Why doesn’t my scheduled snapshot run automatically?

• Kopia’s Web UI scheduling relies on the Kopia server process running continuously. Make sure it’s enabled and active:

  sudo systemctl status kopia-server

• If your server was down or asleep during the scheduled time, the snapshot will be run later (it is configurable).

---

❓ Can I restore files directly from the Web UI?

Yes. Go to Snapshots → (select snapshot). You can download individual files directly. Select Mount as Local Filesystem to make a Read only mount of repo. Or select Restore Files and Directories → (Enter destination) and hit Begin Restore to restore the snapshot to selected folder.

Or you can also use CLI:

kopia snapshot restore <snapshot-id> /restore/path

---

❓ Where is my Kopia configuration stored?

• System service config (if you used systemd): /root/.config/kopia/repository.config

---

❓ How can I check backup integrity?

kopia snapshot verify

kopia snapshot verify checks repository integrity. To remove unreferenced data or force retention cleanup, use Kopia maintenance/GC. Maintenance is scheduled to run by default as long as service is running.

---

❓ I lost my Kopia password. Can I recover my backups?

No. Kopia encrypts everything with your password-derived key. Without it, the data is unrecoverable. Always store your password securely (password manager or printed copy).

---

❓ How do I move my repository to a new machine?

1. Copy the repository storage (e.g., S3 bucket or /backup/kopia-repo directory) to the new system.
2. Install Kopia on the new host.
3. In the Web UI, choose “Connect repository”.
4. Enter the same backend configuration and password. Your snapshots will appear automatically.

---

❓ Can I run Kopia inside Docker instead?

Yes but it is out of scope of this gude.

---

❓ Do I need to back up thumbnails and transcodes?

They’re optional. Immich can regenerate them after restore via the Admin panel. To save space, you can exclude them in policy settings:

Exclude paths:
  /thumbs/*
  /encoded-video/*

---