argento/IMMICH-MIGRATION.md

Immich migration plan

One-time migration of photos from Nextcloud into Immich's native library.

• Source: /opt/argento/docker/nextcloud/data/timothykim/files/Photos/ (338 GB, ~58k files)
• Target: Immich native library on threeteras pool (/opt/argento/docker/immich/library/)
• Tool: official immich-cli via Immich HTTP API
• Expected wall time: ~1 day if videos are short clips, 2-3 days if significant long/4K video

1. Pause the backup cron (optional but recommended)

crontab -e   # comment out scripts/backup.sh line

Re-enable after migration completes.

2. Get an Immich API key

Immich UI -> Account Settings -> API Keys -> New (label it "migration"). Save the key.

3. Get the direct container IP (skips nginx/TLS overhead)

IMMICH_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}} {{end}}' immich_server | awk '{print $1}')
echo $IMMICH_IP

4. Dry-run on a small subfolder first

Pick one year or album. The CLI runs inside a container with the source bind-mounted read-only:

docker run -it --rm \
  -v /opt/argento/docker/nextcloud/data/timothykim/files/Photos/<small-subfolder>:/import:ro \
  ghcr.io/immich-app/immich-cli:latest \
  upload --server http://$IMMICH_IP:2283/api --key <KEY> --dry-run --recursive /import

5. Real run on that subfolder, verify in UI

Drop --dry-run, run, then in Immich check: dates, GPS, thumbnails look correct.

6. Full migration in tmux

tmux new -s immich-migrate

docker run -it --rm \
  -v /opt/argento/docker/nextcloud/data/timothykim/files/Photos:/import:ro \
  ghcr.io/immich-app/immich-cli:latest \
  upload --server http://$IMMICH_IP:2283/api --key <KEY> --recursive -c 4 /import

# Ctrl-b d to detach; tmux attach -t immich-migrate to resume

Notes:

• No --album flag -- photos land in the main timeline, organized by date.
• -c 4 is the default concurrency. Raise carefully; Immich's ingest + ML post-processing can saturate CPU/RAM.
• Safe to Ctrl-C and re-run -- the CLI hashes files client-side and skips anything already uploaded.

7. Watch resources during upload

In another terminal:

docker stats immich_server immich_postgres immich_machine_learning

If memory pressure gets bad, lower -c on the next restart.

8. Wait for background jobs

Immich UI -> Administration -> Jobs. Watch these drain (can take hours to days):

• Thumbnail Generation
• Metadata Extraction
• Smart Search (CUDA)
• Face Detection + Recognition (CUDA)
• Video Conversion (NVENC)

9. Verify counts

find /opt/argento/docker/nextcloud/data/timothykim/files/Photos/ -type f | wc -l
# Compare to Immich UI -> Administration -> Server Stats

If mismatch, re-run step 6 (will only upload the missing files).

10. Spot-check the library

Random samples across years, verify EXIF dates, GPS locations, faces grouping reasonably.

11. Clean up Nextcloud (only after you're satisfied)

Delete Photos/ from Nextcloud UI -> empty trashbin -> verify zfs list shows nextcloud/data shrank.

12. Re-enable backup cron

Uncomment the cron line, then run scripts/backup.sh manually once to get a fresh full backup with the new Immich library.

Rollback

If anything goes wrong before step 11, Nextcloud is untouched. Worst case: delete all Immich assets from UI (or wipe /opt/argento/docker/immich/library/ and reinit the DB), start over.