mirror of
https://github.com/acedanger/shell.git
synced 2025-12-06 07:50:11 -08:00
2540c2d50b
- Updated README.md to streamline content and improve navigation with a new Quick Navigation section. - Consolidated detailed Plex backup descriptions into dedicated documentation files. - Added comprehensive Docker Bootstrap Testing Framework documentation. - Created Immich backup enhancement summary and migration summary documents. - Implemented webhook notifications and Backblaze B2 integration in Immich backup scripts. - Centralized logging for Immich backup operations and updated configuration requirements. - Restructured Telegram bot project documentation for better clarity and organization. - Enhanced .gitignore to include environment files and Backblaze CLI tool. - Updated dotfiles README to reference new testing documentation. Resolves Documentation review #11.
166 lines
4.7 KiB
Markdown
166 lines
4.7 KiB
Markdown
# 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
|
|
```
|