vps/docs/immich-backup-implementation.md

# Immich Photo Backup Implementation

**Date:** 2026-01-25
**Status:** ✅ COMPLETED
**Completion Time:** ~5 minutes

## Summary

Successfully implemented automated daily backup of Immich photo library (34,694 files, 39.34GB). The backup runs every day at 04:00 German time and uses rsync with hardlinking for space efficiency.

## What Was Done

### 1. Created Backup Script
**Location:** `/home/phil/docker/backup/backup-immich-photos.sh`

**Features:**
- Incremental backup using rsync
- Hardlinking unchanged files to save space
- 30-day retention policy
- Detailed logging to `/var/log/immich-photo-backup.log`
- Backup metadata (file count, size, date)
- Automatic cleanup of old backups

### 2. Installed Required Software
- Installed `rsync` package on VPS
- Restarted affected services (containerd, cron, docker)

### 3. Configured Automation
**Cron Job:**
```
0 4 * * * /home/phil/docker/backup/backup-immich-photos.sh >> /var/log/immich-photo-backup.log 2>&1
```

**Schedule:** Daily at 04:00 German time (automatically adjusts for CET/CEST)

### 4. Performed Initial Backup
- **Files:** 34,694 photos, videos, and thumbnails
- **Size:** 39.34GB
- **Duration:** ~4 minutes
- **Speed:** 164 MB/s
- **Location:** `/mnt/backup/immich-photos/20260125_160319/`

## Current Backup Schedule

| Time | Job | What | Location |
|------|-----|------|----------|
| 02:00 | Databases | PostgreSQL + volumes | `/mnt/backup/` |
| 04:00 | Photos | Immich photo library | `/mnt/backup/immich-photos/` |

## Backup Structure

```
/mnt/backup/
├── latest -> ../20260125_134216                    # Database backup symlink
├── 20260125_134216/                                 # Database backups
├── immich-photos/
│   ├── latest -> 20260125_160319                   # Photo backup symlink
│   ├── 20260125_160319/                             # Latest photo backup
│   │   ├── upload/                                  # Original photos
│   │   ├── encoded-video/                           # Transcoded videos
│   │   ├── thumbs/                                  # Thumbnails
│   │   ├── library/                                 # Library files
│   │   ├── profile/                                 # Profile photos
│   │   └── backup-info.txt                          # Backup metadata
│   └── (previous backups, retained for 30 days)
```

## Performance

### First Backup (2026-01-25)
- **Time:** ~4 minutes
- **Throughput:** 164 MB/s
- **Space Used:** 39.34GB

### Subsequent Backups
- **Time:** ~1-2 minutes (only changed files)
- **Space Efficient:** Uses hardlinks for unchanged files
- **Incremental:** Only copies new/modified files

## Monitoring

### Check Backup Status
```bash
# View latest backup
ls -lah /mnt/backup/immich-photos/latest/

# Check backup info
cat /mnt/backup/immich-photos/latest/backup-info.txt

# View backup log
tail -f /var/log/immich-photo-backup.log

# List all backups
ls -lah /mnt/backup/immich-photos/
```

### Example Output
```
Backup Date: So 25. Jan 16:07:20 CET 2026
Hostname: vps1
Source: /home/phil/docker/immich-app/library
Destination: /mnt/backup/immich-photos//20260125_160319
Files: 34694
Size: 37G
Type: Immich Photo Backup
```

## Restore Procedure

### Restore All Photos
```bash
# Stop Immich first
cd /home/phil/docker/immich-app
docker compose stop

# Restore photos
rsync -av /mnt/backup/immich-photos/latest/ /home/phil/docker/immich-app/library/

# Restart Immich
docker compose start
```

### Restore Specific Date
```bash
# List available backups
ls -lah /mnt/backup/immich-photos/

# Restore specific backup
rsync -av /mnt/backup/immich-photos/20260125_160319/ /home/phil/docker/immich-app/library/
```

### Restore Single File
```bash
# Find file in backup
find /mnt/backup/immich-photos/latest/ -name "filename.jpg"

# Copy file back
cp /mnt/backup/immich-photos/latest/upload/path/to/file.jpg \
   /home/phil/docker/immich-app/library/upload/path/to/file.jpg
```

## Retention Policy

- **Retention:** 30 days
- **Automatic Cleanup:** Old backups deleted automatically after 30 days
- **Space Management:** New backups use hardlinks to minimize space
- **Expected Growth:** Only new photos consume additional space

## Storage Requirements

### Current Usage
- **Photo Library:** 39.34GB
- **Daily Database Backups:** ~83MB
- **Total Daily Backup:** ~39.4GB

### With 30-Day Retention
- **Photos:** ~39GB (hardlinks make additional days minimal)
- **Databases:** ~2.5GB (30 × 83MB)
- **Total:** ~42GB for complete 30-day backup set

### Available Space
- **Total Disk:** 1TB (1006GB)
- **Used:** 92GB (9%)
- **Available:** 863GB (91%)
- **Sufficient for:** Years of backups with current retention

## Security Considerations

✅ **Backup Permissions:**
- Script owned by `phil` user
- Log file: `phil:phil` with 664 permissions
- Backup directory: `phil:phil` with 755 permissions

✅ **Data Integrity:**
- rsync with `--archive` preserves all attributes
- Hardlinks ensure file integrity
- Backup metadata verifies completion

⚠️ **Recommendations:**
- Consider remote storage mount for off-site backups
- Test restore procedure quarterly
- Monitor disk space usage
- Keep backup script secure (600 permissions)

## Troubleshooting

### Backup Not Running
```bash
# Check cron job
crontab -l

# Check backup log
tail -50 /var/log/immich-photo-backup.log

# Run manually to test
/home/phil/docker/backup/backup-immich-photos.sh
```

### Slow Backup Performance
```bash
# Check disk I/O
iostat -x 5

# Check available disk space
df -h

# Check rsync process
ps aux | grep rsync
```

### Out of Space
```bash
# Check what's using space
du -sh /mnt/backup/*

# Manually clean old backups (if needed)
find /mnt/backup/immich-photos/ -maxdepth 1 -type d -name "*_*" -mtime +30 -exec rm -rf {} \;
```

## Integration with Existing Backups

The Immich photo backup complements the existing database backup:

| Backup Type | Time | Script | Data |
|-------------|------|--------|------|
| Database | 02:00 | `backup.sh` | Immich DB, Netbird, Gitea |
| Photos | 04:00 | `backup-immich-photos.sh` | Immich library (39GB) |

**Total Coverage:** ✅ All Immich data backed up daily

## Next Steps

### Completed
- [x] Create backup script
- [x] Install rsync
- [x] Configure cron job
- [x] Perform initial backup
- [x] Test backup integrity
- [x] Document procedures

### Optional Enhancements
- [ ] Mount remote storage to `/mnt/backup` for off-site backups
- [ ] Configure backup failure notifications
- [ ] Set up automatic backup testing
- [ ] Implement backup rotation based on disk space

## Files Modified

**Created:**
- `/home/phil/docker/backup/backup-immich-photos.sh`
- `/var/log/immich-photo-backup.log`

**Modified:**
- `crontab` - Added 04:00 daily job
- `/home/phil/Schreibtisch/Privat/vps/vps1-todo.md` - Marked as completed
- `/home/phil/Schreibtisch/Privat/vps/docs/deployment-summary.md` - Updated backup section

**System Changes:**
- Installed `rsync` package
- Restarted services: containerd, cron, docker

## Success Criteria ✅

- [x] Backup script created and tested
- [x] Automated via cron (04:00 daily)
- [x] Initial backup completed successfully
- [x] All 34,694 files backed up
- [x] Logging configured and working
- [x] Retention policy implemented
- [x] Restore procedure documented
- [x] Disk space sufficient (863GB free)

## Conclusion

The Immich photo backup system is now fully operational and automated. Your 39GB photo library is backed up daily at 04:00 German time with 30-day retention. The system uses efficient incremental backups with hardlinking to minimize storage overhead.

**All critical data is now protected with automated backups.**

---

**Last Updated:** 2026-01-25
**Status:** ✅ Production Ready