diff --git a/02_Projects/Homelab Todo List.md b/02_Projects/Homelab Todo List.md index 0f11ffe..aadeb8c 100644 --- a/02_Projects/Homelab Todo List.md +++ b/02_Projects/Homelab Todo List.md @@ -13,11 +13,11 @@ Prioritized list of things Claudio wants to do with his homelab. Last updated: 2 ## Hosting & Apps -- [ ] Host Mealie (meal planning) -- [ ] Host Nextcloud -- [ ] Paperless-ngx public access setup -- [ ] Immich: migrate Alena + family users once stable (see [[Frusetik Access Architecture]] for access model) -- [ ] Immich: stop iCloud + Synology Photos sync, use Immich exclusively +- [ ] Immich: test thoroughly and validate for production use (see [[Immich Testing Plan]]) + - [ ] Automatic phone backup (iOS) + - [ ] Immich library + database backup/restore + - [ ] Public sharing guest experience + - [ ] 1-week stability run ## Infrastructure Cleanup diff --git a/02_Projects/Immich Testing Plan.md b/02_Projects/Immich Testing Plan.md new file mode 100644 index 0000000..3ee7664 --- /dev/null +++ b/02_Projects/Immich Testing Plan.md @@ -0,0 +1,231 @@ +# Immich Testing & Validation Plan + +**Goal:** Decide if Immich is stable and complete enough to replace iCloud Photos + Synology Photos as Claudio's primary photo management system. + +**Valid for:** Claudio's personal use + eventual family migration (Alena + others) + +**Last updated:** 2026-04-01 + +--- + +## What We Need to Validate + +1. Automatic phone backup (iOS + Android) +2. Immich library + database backup and restore +3. Public sharing with non-account holders (guest experience) +4. Overall stability under real-world use + +--- + +## 1. Automatic Phone Backup + +### How it works + +Immich has a mobile app (iOS + Android) with two backup modes: + +- **In-app backup:** User opens the app, goes to the album they want to back up, and hits the backup icon. New photos/videos in that album upload automatically. +- **Background backup (Android):** The app periodically checks selected albums in the background and uploads new photos without opening the app. +- **iOS background backup:** iOS restricts true background processing, so the app relies on resume-triggered uploads when you open or return to the app. + +### What to test + +| Test | Expected behavior | Pass criteria | +|---|---|---| +| Select album for backup | Immich shows only that album's new photos | Correct album selected | +| New photo taken → app open | Photo appears on server within minutes | Upload completes | +| Multiple new photos at once | All upload, progress shown | No dropped uploads | +| App killed, reopened | Pending uploads resume | No data loss | +| Battery impact | Not excessive (subjective) | Acceptable to Claudio | +| Backup of HEIC/HEVC videos | Transcoded or original preserved | Plays back correctly | +| Backup while on mobile data | Configurable: WiFi only or all networks | Respects setting | + +### Action items + +- [ ] Install Immich app on Claudio's iPhone, log in +- [ ] Enable backup for Camera Roll album (or most important album) +- [ ] Take 5 test photos, wait 2 min, verify on server +- [ ] Enable background backup if Android (not applicable for iOS) +- [ ] Test backup while on LTE/mobile data (with WiFi-only disabled) +- [ ] Check battery usage after 24h with background backup + +### Notes from research + +- iOS app uses `https://demo.immich.app` as demo server endpoint for initial setup — not needed for self-hosted +- The app connects to `immich.frusetik.com` directly (behind Pangolin) +- If Pangolin auth is ever re-enabled on Immich, mobile backup will break — keep Immich **Not Protected** in Pangolin +- For Alena's Android phone: test background backup there too when migration time comes + +--- + +## 2. Immich Library + Database Backup + +### What needs to be backed up + +Immich stores three critical data volumes: + +| Volume | What it contains | Size | +|---|---|---| +| `UPLOAD_LOCATION` (`immich-upload`) | Original photos + videos | Largest | +| `DB_DATA_LOCATION` (`pgdata`) | PostgreSQL database (metadata, thumbnails, users, albums) | Medium | +| `THUMB_LOCATION` (`immich-thumbs`) | Generated thumbnails | Medium | +| `ENC_DATA_LOCATION` (`immich-encrypted`) | Encrypted files (if used) | Varies | + +### Backup approach + +**Database backup (PostgreSQL):** +```bash +docker exec immich_postgres pg_dumpall \ + --clean \ + --if-exists \ + --username="${DB_USERNAME}" \ + > backup_$(date +%Y%m%d_%H%M%S).sql +``` + +**Volume backup:** +```bash +# Using docker volume backup +docker run --rm \ + -v immich_app_upload:/src \ + -v /path/to/backups:/dst \ + alpine \ + tar czf /dst/immich_upload_$(date +%Y%m%d).tar.gz -C /src . +``` + +### Recommended backup script (from Immich docs template) + +The official backup script (`docker/immich/backup.sh` in the Immich repo) handles: +- Pause the Immich server before backup +- Run `pg_dumpall` to SQL file +- Backup the upload volume +- Unpause the server +- Retention: keeps last N backups + +### What to test + +| Test | Expected behavior | Pass criteria | +|---|---|---| +| Run `pg_dumpall` backup | Clean SQL file created, no errors | File size > 0, valid SQL | +| Restore from SQL dump | Immich starts with correct data | All albums, users, metadata present | +| Volume backup + restore | Photos play back correctly | No corruption | +| Test restore on fresh Immich install | Full recovery | All data intact | +| Backup during active upload | No corruption, consistent state | Server pauses cleanly | + +### Action items + +- [ ] Locate Immich docker volumes on the home lab machine (`docker volume ls | grep immich`) +- [ ] Write and test `pg_dumpall` backup script +- [ ] Test backup of `UPLOAD_LOCATION` volume +- [ ] Do a **practice restore** to a test Immich instance +- [ ] Set up automated daily backup via cron +- [ ] Verify backup lands offsite (parents' NAS or cloud storage) +- [ ] Document exact restore procedure — time to restore SLA + +### Notes from research + +- Immich docs explicitly recommend `pg_dumpall --clean --if-exists` over plain `pg_dump` +- Database backup should be taken with Immich server **paused or in maintenance mode** to ensure consistency +- Volume snapshots via docker or restic are the most reliable for file-level backups +- The official Immich Docker setup already uses named volumes — good for scripted backup + +--- + +## 3. Public Sharing with Non-Account Holders + +### How it works + +Immich has a built-in **public sharing** feature: + +- Create an album (or select an existing one) +- Generate a public share link +- Share the link with anyone — no Immich account needed +- Recipients can **view** and **download** photos from that album + +The shared link is read-only for non-account holders. + +### What to test + +| Test | Expected behavior | Pass criteria | +|---|---|---| +| Create public link for album | Unique URL generated | Link works immediately | +| Open link in incognito browser | Photos load without login | No auth prompt | +| Photos load on mobile browser | Thumbnails + full-size load | Responsive, no broken images | +| Download single photo | Correct file, original quality | Matches uploaded file | +| Download full album as ZIP | ZIP with all photos | Correct files, no corruption | +| Link expiry settings | Link works before expiry, blocked after | Respects setting | +| Shared video playback | Video plays in browser | No plugin needed | +| Very large album (500+ photos) | Loads without crashing | Performance acceptable | + +### Action items + +- [ ] Create test album with 10 photos, generate public link +- [ ] Open link on laptop (Chrome, Firefox, Safari) +- [ ] Open link on phone (Chrome/Safari) without being logged in +- [ ] Test download of a photo from shared link +- [ ] Test download ZIP of entire album +- [ ] Test sharing a video — does it play or only download? +- [ ] Verify no Immich instance details leak in shared page (no internal IPs, no API endpoints visible) +- [ ] Set up immich-public-proxy if extra privacy layer is desired (see notes below) + +### Notes from research + +- **immich-public-proxy** (GitHub: `alangrainger/immich-public-proxy`) — a separate proxy that front-ends Immich sharing to hide instance details and add extra safety for truly public links. Worth evaluating if sharing with strangers is a core use case. +- Built-in sharing is already functional without extra proxy +- Public links do not require the viewer to have an Immich account +- Album visibility: only explicitly shared albums are accessible — nothing else is exposed + +--- + +## 4. Overall Stability + +### What to test + +| Test | Expected behavior | Pass criteria | +|---|---|---| +| Upload 100+ photos via web | All processed, thumbnails generated | No dropped uploads, no errors | +| Search by date, location | Correct results | Relevant photos found | +| Create album, add photos | Album contains correct photos | Album persists after reload | +| Delete photo | Removed from server + app | Gone from all views | +| Duplicate detection | Duplicates flagged | Accurate detection | +| Memory usage on server | Not excessive under load | < 4GB RAM under normal use | +| Long-running server (1 week) | No crashes, no memory leaks | Stable, no restarts needed | + +### Action items + +- [ ] Upload 50-100 test photos via web upload +- [ ] Test search (date range, maybe location if geolocation is on) +- [ ] Test duplicate detection +- [ ] Monitor server resource usage for 24h +- [ ] Let it run for 1 week before declaring stable + +--- + +## Decision Criteria + +Before Claudio commits to Immich as primary: + +| Criterion | Must pass before going live | +|---|---| +| Phone backup works reliably | ✅ | +| Backup + restore tested | ✅ | +| Public sharing guest experience good | ✅ | +| Stable for at least 1 week | ✅ | + +--- + +## Migration Path + +Once all criteria pass: + +``` +Phase 1: Claudio uses Immich alongside iCloud + Synology Photos (dual feed) +Phase 2: Claudio confirms Immich backup is trustworthy → stop iCloud sync +Phase 3: Alena + family migration (per their capacity and interest) +Phase 4: Decommission Synology Photos (or keep as secondary backup) +``` + +--- + +## Related + +- [[Frusetik Access Architecture]] — Immich is NOT protected by Pangolin auth (required for iOS app compatibility) +- [[Homelab Todo List]] — backup system items tracked separately