# Immich Management Scripts

This directory contains scripts for managing and backing up Immich photo management system.

## Scripts

### backup-immich.sh

Complete backup script for Immich installation that creates backups of:

- PostgreSQL database (using pg_dumpall as recommended by Immich)
- User upload directories (photos, videos, and metadata)

**Requirements:**

- `.env` file in the parent directory (`/home/acedanger/shell/.env`) with:
  - `DB_USERNAME` - PostgreSQL username
  - `DB_DATABASE_NAME` - Database name  
  - `UPLOAD_LOCATION` - Path to Immich upload directory
- Docker containers: `immich_postgres` and `immich_server`

**Usage:**

```bash
./backup-immich.sh
```

**Backup Location:**

- Database: `../immich_backups/immich_db_backup_YYYYMMDD_HHMMSS.sql.gz`
- Uploads: `../immich_backups/immich_uploads_YYYYMMDD_HHMMSS.tar.gz`

**Features:**

- Automatic container pausing/resuming during backup
- Comprehensive error handling and cleanup
- Backup validation and health checks
- Automatic compression
- Old backup cleanup (configurable)
- Centralized logging to `/home/acedanger/shell/logs/`
- Detailed progress reporting and timestamped logs
- 🔔 **Webhook notifications** to notify.peterwood.rocks/lab
- ☁️ **Backblaze B2 integration** for off-site backup storage
- 📊 **File size reporting** in notifications

## Configuration

The scripts expect a `.env` file in the parent directory with the following variables:

```bash
# Database configuration
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
UPLOAD_LOCATION=/path/to/immich/uploads

# Notification settings
WEBHOOK_URL="https://notify.peterwood.rocks/lab"

# Backblaze B2 settings (optional)
# Get these from your B2 account: https://secure.backblaze.com/app_keys.htm
# B2_APPLICATION_KEY_ID=your_key_id_here
# B2_APPLICATION_KEY=your_application_key_here
# B2_BUCKET_NAME=your_bucket_name_here

# Optional: Backup retention (days)
BACKUP_RETENTION_DAYS=30
```

## Backup Strategy

Based on Immich's official backup recommendations:

1. **Database Backup**: Uses `pg_dumpall` with `--clean` and `--if-exists` flags
2. **Upload Directory**: Complete archive of upload location including:
   - upload/ - Original photos and videos
   - profile/ - User profile images
   - thumbs/ - Generated thumbnails
   - encoded-video/ - Transcoded videos
   - library/ - Library metadata
   - backups/ - Existing backup files (excluded from new backups)

## Notifications 🔔

The backup script sends notifications to your webhook URL with:

- 🚀 **Start notification**: When backup begins
- ✅ **Success notification**: When backup completes successfully with file sizes
- ⚠️ **Warning notification**: When backup succeeds but B2 upload fails
- 🚨 **Error notification**: When backup fails

Example notification:

```
📦 Database: immich_db_backup_20250526_215913.sql.gz (150MB)
📁 Uploads: immich_uploads_20250526_215913.tar.gz (25GB)
☁️ Successfully uploaded to B2 bucket: my-immich-backups
```

## Backblaze B2 Integration ☁️

### Setup B2 Account

1. Create a [Backblaze B2 account](https://www.backblaze.com/b2/cloud-storage.html)
2. Create a new bucket for Immich backups
3. Generate application keys:
   - Go to: <https://secure.backblaze.com/app_keys.htm>
   - Create new key with read/write access to your bucket

### Configure B2 in .env

Add these variables to your `.env` file:

```bash
B2_APPLICATION_KEY_ID=your_key_id_here
B2_APPLICATION_KEY=your_application_key_here
B2_BUCKET_NAME=your_bucket_name_here
```

### B2 Features

- **Automatic upload**: Backup files are uploaded to B2 after creation
- **Organized storage**: Files stored in `immich-backups/` folder in your bucket
- **Error handling**: Script continues if B2 upload fails (local backup preserved)
- **Progress tracking**: Upload status included in notifications

The B2 CLI tool (`b2-linux`) is included in this directory and doesn't require separate installation.

## Restore Process

For complete restore instructions, see: <https://immich.app/docs/administration/backup-and-restore/>

1. **Database Restore:**

   ```bash
   docker exec -i immich_postgres psql -U postgres < immich_db_backup.sql
   ```

2. **Upload Directory Restore:**

   ```bash
   tar -xzf immich_uploads_backup.tar.gz -C /target/location
   ```

## Logs

Backup logs and performance metrics are stored in the main shell logs directory (`/home/acedanger/shell/logs/`).

## Monitoring

The backup script includes:

- Progress indicators for long-running operations
- Size validation for backup files
- Container status monitoring
- Automatic cleanup procedures
- Comprehensive error reporting

## Automation

To automate backups, add to crontab:

```bash
# Daily Immich backup at 2:00 AM
0 2 * * * /home/acedanger/shell/immich/backup-immich.sh >> /home/acedanger/shell/logs/immich-backup.log 2>&1
```