mirror of
https://github.com/acedanger/shell.git
synced 2025-12-06 00:00:13 -08:00
feat: Implement comprehensive restore functionality for Immich
- Added `restore-immich.sh` script to handle complete restoration from backups. - Implemented database restoration with integrity checks and error handling. - Added uploads restoration with proper ownership and permissions setup. - Introduced validation script `validate-immich-backups.sh` for backup integrity checks. - Created test suite `test-immich-restore.sh` to validate restoration functionality with mock data. - Enhanced logging and notification features for restoration processes. - Updated README.md with detailed usage instructions for backup and restore workflows.
This commit is contained in:
Peter Wood
237
immich/README.md
237
immich/README.md
@@ -436,25 +436,234 @@ For complete restore instructions, see: <https://immich.app/docs/administration/
|
||||
tar -xzf immich_uploads_YYYYMMDD_HHMMSS.tar.gz -C /target/location
|
||||
```
|
||||
|
||||
## Logs
|
||||
### restore-immich.sh
|
||||
|
||||
Backup logs and performance metrics are stored in the main shell logs directory (`/home/acedanger/shell/logs/`).
|
||||
Complete restoration script for Immich installation that restores from backups created by `backup-immich.sh`:
|
||||
|
||||
## Monitoring
|
||||
- PostgreSQL database restoration (with decompression and integrity checks)
|
||||
- User upload directories restoration (photos, videos, and metadata)
|
||||
- Container management (stop/start services during restoration)
|
||||
- Comprehensive validation and error handling
|
||||
|
||||
The backup script includes:
|
||||
**Requirements:**
|
||||
|
||||
- Progress indicators for long-running operations
|
||||
- Size validation for backup files
|
||||
- Container status monitoring
|
||||
- Automatic cleanup procedures
|
||||
- Comprehensive error reporting
|
||||
- `.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`
|
||||
- Valid backup files created by `backup-immich.sh`
|
||||
|
||||
## Automation
|
||||
|
||||
To automate backups, add to crontab:
|
||||
**Usage:**
|
||||
|
||||
```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
|
||||
./restore-immich.sh --db-backup <path> --uploads-backup <path> [OPTIONS]
|
||||
```
|
||||
|
||||
**Required Arguments:**
|
||||
|
||||
- `--db-backup PATH` - Path to database backup file (.sql.gz)
|
||||
- `--uploads-backup PATH` - Path to uploads backup file (.tar.gz)
|
||||
|
||||
**Optional Arguments:**
|
||||
|
||||
- `--dry-run` - Show what would be restored without making changes
|
||||
- `--skip-db` - Skip database restoration (uploads only)
|
||||
- `--skip-uploads` - Skip uploads restoration (database only)
|
||||
- `--help` - Show help message and exit
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Complete restoration (recommended to run dry-run first)
|
||||
./restore-immich.sh \
|
||||
--db-backup ../immich_backups/immich_db_backup_20250603_120000.sql.gz \
|
||||
--uploads-backup ../immich_backups/immich_uploads_20250603_120000.tar.gz \
|
||||
--dry-run
|
||||
|
||||
# Actual restoration after verifying dry-run
|
||||
./restore-immich.sh \
|
||||
--db-backup ../immich_backups/immich_db_backup_20250603_120000.sql.gz \
|
||||
--uploads-backup ../immich_backups/immich_uploads_20250603_120000.tar.gz
|
||||
|
||||
# Restore database only
|
||||
./restore-immich.sh \
|
||||
--db-backup ../immich_backups/immich_db_backup_20250603_120000.sql.gz \
|
||||
--uploads-backup ../immich_backups/immich_uploads_20250603_120000.tar.gz \
|
||||
--skip-uploads
|
||||
|
||||
# Restore uploads only
|
||||
./restore-immich.sh \
|
||||
--db-backup ../immich_backups/immich_db_backup_20250603_120000.sql.gz \
|
||||
--uploads-backup ../immich_backups/immich_uploads_20250603_120000.tar.gz \
|
||||
--skip-db
|
||||
```
|
||||
|
||||
**Safety Features:**
|
||||
|
||||
- **Dry-run mode**: Preview all operations without making changes
|
||||
- **File validation**: Verifies backup file integrity before restoration
|
||||
- **Container management**: Safely stops/starts services during restoration
|
||||
- **Cleanup on failure**: Automatically restores services if restoration fails
|
||||
- **Comprehensive logging**: All operations logged to `../logs/immich-restore.log`
|
||||
- **Notification support**: Sends webhook notifications for restoration status
|
||||
|
||||
### validate-immich-backups.sh
|
||||
|
||||
Validation script that checks the integrity and completeness of Immich backup files:
|
||||
|
||||
- File integrity validation (gzip and tar.gz corruption detection)
|
||||
- Backup pairing verification (matching database and upload backups)
|
||||
- Size and content validation
|
||||
- Restoration command generation for valid backups
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
./validate-immich-backups.sh [backup_directory]
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
|
||||
- `backup_directory` - Directory containing backup files (default: `../immich_backups`)
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Validate backups in default directory
|
||||
./validate-immich-backups.sh
|
||||
|
||||
# Validate backups in specific directory
|
||||
./validate-immich-backups.sh /path/to/backups
|
||||
|
||||
# Example output for valid backups
|
||||
=== IMMICH BACKUP VALIDATION ===
|
||||
Backup directory: ../immich_backups
|
||||
|
||||
=== DATABASE BACKUPS ===
|
||||
Validating: immich_db_backup_20250603_120000.sql.gz
|
||||
✓ File size OK (45M)
|
||||
✓ Gzip file integrity OK
|
||||
✓ SQL content appears valid
|
||||
|
||||
=== UPLOAD BACKUPS ===
|
||||
Validating: immich_uploads_20250603_120000.tar.gz
|
||||
✓ File size OK (2.1G)
|
||||
✓ Tar.gz file integrity OK
|
||||
✓ Archive contains 15,234 files/directories
|
||||
|
||||
=== RESTORATION COMMANDS ===
|
||||
To restore the most recent complete backup:
|
||||
|
||||
# Dry run (recommended first):
|
||||
./restore-immich.sh \
|
||||
--db-backup "../immich_backups/immich_db_backup_20250603_120000.sql.gz" \
|
||||
--uploads-backup "../immich_backups/immich_uploads_20250603_120000.tar.gz" \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
## Backup and Restore Workflow
|
||||
|
||||
### 1. Regular Backup
|
||||
|
||||
```bash
|
||||
# Run daily backup (typically via cron)
|
||||
./backup-immich.sh
|
||||
```
|
||||
|
||||
### 2. Validate Backups
|
||||
|
||||
```bash
|
||||
# Check backup integrity periodically
|
||||
./validate-immich-backups.sh
|
||||
```
|
||||
|
||||
### 3. Restoration Process
|
||||
|
||||
```bash
|
||||
# Step 1: Validate available backups and get commands
|
||||
./validate-immich-backups.sh
|
||||
|
||||
# Step 2: Test restoration with dry-run
|
||||
./restore-immich.sh \
|
||||
--db-backup "path/to/db_backup.sql.gz" \
|
||||
--uploads-backup "path/to/uploads_backup.tar.gz" \
|
||||
--dry-run
|
||||
|
||||
# Step 3: Perform actual restoration
|
||||
./restore-immich.sh \
|
||||
--db-backup "path/to/db_backup.sql.gz" \
|
||||
--uploads-backup "path/to/uploads_backup.tar.gz"
|
||||
```
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Partial Restoration
|
||||
|
||||
For specific restoration scenarios:
|
||||
|
||||
```bash
|
||||
# Database only (preserve existing uploads)
|
||||
./restore-immich.sh \
|
||||
--db-backup "db_backup.sql.gz" \
|
||||
--uploads-backup "uploads_backup.tar.gz" \
|
||||
--skip-uploads
|
||||
|
||||
# Uploads only (preserve existing database)
|
||||
./restore-immich.sh \
|
||||
--db-backup "db_backup.sql.gz" \
|
||||
--uploads-backup "uploads_backup.tar.gz" \
|
||||
--skip-db
|
||||
```
|
||||
|
||||
### Emergency Recovery
|
||||
|
||||
In case of data loss or corruption:
|
||||
|
||||
1. **Stop Immich services**: `docker stop immich_server immich_postgres`
|
||||
2. **Validate backups**: `./validate-immich-backups.sh`
|
||||
3. **Dry-run restoration**: Use `--dry-run` first
|
||||
4. **Restore data**: Remove `--dry-run` flag
|
||||
5. **Verify functionality**: Check Immich web interface
|
||||
|
||||
### Monitoring and Logs
|
||||
|
||||
All scripts log to the centralized logging directory:
|
||||
|
||||
- **Backup logs**: `../logs/immich-backup.log`
|
||||
- **Restoration logs**: `../logs/immich-restore.log`
|
||||
- **Validation logs**: `../logs/immich-validation.log`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Container not found**: Ensure Docker containers are running
|
||||
2. **Permission denied**: Check file permissions and Docker access
|
||||
3. **Database connection failed**: Verify PostgreSQL credentials in `.env`
|
||||
4. **Insufficient disk space**: Check available space before restoration
|
||||
5. **Backup file corruption**: Use `validate-immich-backups.sh` to check integrity
|
||||
|
||||
### Recovery Steps
|
||||
|
||||
1. Check logs in `../logs/` directory
|
||||
2. Verify `.env` file configuration
|
||||
3. Ensure Docker containers are accessible
|
||||
4. Validate backup file integrity
|
||||
5. Use dry-run mode to test operations
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
Required `.env` file structure:
|
||||
|
||||
```bash
|
||||
# Database Configuration
|
||||
DB_USERNAME=postgres
|
||||
DB_DATABASE_NAME=immich
|
||||
|
||||
# Upload Directory
|
||||
UPLOAD_LOCATION=/path/to/immich/uploads
|
||||
|
||||
# Optional: Notification Settings
|
||||
NTFY_URL=https://ntfy.sh/your-topic
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user