homelab-configs/kopia-restore-guide.md

Kopia Restore Guide

Last Updated: May 8, 2026
Applies To: Both Kopia repositories on siklos (192.168.88.27)

---

⚠️ Critical: What You Need to Restore

You need two things to restore from Backblaze B2. Without either one, data is unrecoverable:

1. Repository password — stored in credentials.md
2. Backblaze B2 account access — credentials in credentials.md

Do not store these only on siklos. Keep them in a password manager or printed copy somewhere safe. If siklos dies and you haven't saved the password elsewhere, your backup is unreadable.

---

📦 Your Two Repositories

Container	B2 Bucket	What It Backs Up	Port
Kopia	jg-kopia-nextcloud	Nextcloud files + database	51515
Kopia-Immich	jg-kopia-immich	Immich photos + database	51516

---

🔍 Step 1 — List Available Snapshots

SSH to siklos first:

ssh jgitta@siklos

Nextcloud snapshots:

docker exec -e KOPIA_PASSWORD='<password>' Kopia kopia snapshot list

Immich snapshots:

docker exec -e KOPIA_PASSWORD='<password>' Kopia-Immich kopia snapshot list

Each snapshot has an ID like k8adffae645082989d7c0f4f051439332 and a timestamp. You can restore from any snapshot in history — not just the latest.

---

📁 Step 2 — Browse a Snapshot (Find Specific Files)

You can explore a snapshot like a folder before restoring anything:

# List the top-level contents of a snapshot
docker exec -e KOPIA_PASSWORD='<password>' Kopia kopia ls <snapshot-id>

# Drill into a subfolder
docker exec -e KOPIA_PASSWORD='<password>' Kopia kopia ls <snapshot-id>/jgitta/files/Documents

# Search for a specific filename across a snapshot
docker exec -e KOPIA_PASSWORD='<password>' Kopia kopia find <snapshot-id> --name "*.jpg"

This lets you confirm exactly what you want to restore before doing it.

---

♻️ Step 3 — Restore Options

Restore a Single File

docker exec -e KOPIA_PASSWORD='<password>' Kopia kopia restore \
  <snapshot-id>/path/to/filename.jpg \
  /tmp/restore/filename.jpg

Restore a Specific Folder

docker exec -e KOPIA_PASSWORD='<password>' Kopia kopia restore \
  <snapshot-id>/jgitta/files/Photos \
  /tmp/restore/Photos/

Restore an Entire Snapshot

docker exec -e KOPIA_PASSWORD='<password>' Kopia kopia restore \
  <snapshot-id> \
  /tmp/restore/

Note: Restored files land on siklos at /tmp/restore/. From there you can copy them to Nextcloud, Immich, or anywhere else via scp or rsync.

---

🚨 Emergency: Siklos Is Gone — Restore from Scratch

If siklos itself is dead, you can restore to any Linux machine:

1. Install Kopia

curl -s https://kopia.io/signing-key | sudo gpg --dearmor -o /usr/share/keyrings/kopia-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/kopia-keyring.gpg] http://packages.kopia.io/apt/ stable main" | sudo tee /etc/apt/sources.list.d/kopia.list
sudo apt update && sudo apt install kopia

2. Connect to Your B2 Repository

For Nextcloud backup:

kopia repository connect b2 \
  --bucket=jg-kopia-nextcloud \
  --key-id=00522b2471e5f090000000003 \
  --key=K005wv6tlgknxkM9arOJV/tMeOInOQY \
  --password=<repository-password>

For Immich backup:

kopia repository connect b2 \
  --bucket=jg-kopia-immich \
  --key-id=00522b2471e5f090000000004 \
  --key=K005gSepxpWk9hWx/MjWnCKtOiNuKnQ \
  --password=<repository-password>

3. List and Restore

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

The B2 key IDs and application keys above are in credentials.md. Replace <repository-password> with the password from credentials.md.

---

💡 Key Points

• Backblaze "Browse Files" shows encrypted chunks — this is normal and expected. Files are not human-readable in B2 directly.
• Every snapshot is independent — you can restore from last week's snapshot even if today's is corrupted.
• Partial restores are fully supported — restore one file, one folder, or everything.
• Kopia is open source — even if the project were abandoned, you can always download the binary from GitHub and reconnect to your B2 repository as long as you have your password.

---

📋 Restore Checklist

• Have repository password (from credentials.md)
• Have B2 credentials (from credentials.md)
• SSH to siklos (or install Kopia on alternate machine)
• Run snapshot list to find correct snapshot by date
• Use kopia ls to browse and confirm the right files
• Run kopia restore with specific path for targeted restore
• Copy restored files to final destination