LIComputerGuy/media-downloader
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
media-downloader/docs/VERSIONING.md
Todd 0d7b2b1aab Initial commit 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-29 22:42:55 -04:00

9.5 KiB
Raw Permalink Blame History

Media Downloader Versioning & Backup Guide

Version Management

Current Version

The current version is stored in /opt/media-downloader/VERSION:

12.12.1

Versioning Scheme

This project follows Semantic Versioning (SemVer):

MAJOR.MINOR.PATCH (e.g., 6.0.0)

  • MAJOR: Incompatible API changes, major feature overhauls
  • MINOR: New features, backward-compatible changes
  • PATCH: Bug fixes, security patches, backward-compatible fixes

Version History

See CHANGELOG.md for complete version history.

Recent Versions:

  • v6.0.0 (2025-10-26) - Database CLI, ImgInn fixes, installer updates, version control
  • v5.0.0 (2025-10-25) - File hash deduplication, directory reorganization, documentation
  • v4.x - Multi-platform support, scheduler, Immich integration

Backup System Integration

Backup Central Integration

Media Downloader is integrated with Backup Central for automated backups.

Profile ID: profile-media-downloader Schedule: Daily at 00:00 (midnight) Destination: /media/backups/Ubuntu/restic-repo (shared restic repository)

Re-adding the Backup Profile

If you need to recreate the backup profile, run:

cd /opt/media-downloader
sudo ./scripts/add-backup-profile.sh

This script will:

  1. Remove existing profile (if present)
  2. Create new profile with correct settings
  3. Restart Backup Central service
  4. Verify profile was created

What Gets Backed Up

Included:

  • /opt/media-downloader/config/ - All configuration files
  • /opt/media-downloader/database/ - SQLite databases (main + scheduler)
  • /opt/media-downloader/cookies/ - Authentication cookies
  • /opt/media-downloader/sessions/ - Instagram session files
  • /opt/media-downloader/modules/ - All Python modules
  • /opt/media-downloader/wrappers/ - Subprocess wrappers
  • /opt/media-downloader/utilities/ - Utility scripts
  • /opt/media-downloader/scripts/ - Backup and install scripts
  • /opt/media-downloader/*.py - Main application files
  • /opt/media-downloader/VERSION - Version file
  • /opt/media-downloader/CHANGELOG.md - Change log
  • /opt/media-downloader/README.md - Documentation
  • /opt/media-downloader/INSTALL.md - Installation guide
  • /opt/media-downloader/requirements.txt - Dependencies
  • /opt/media-downloader/db - Database CLI wrapper

Excluded:

  • /opt/media-downloader/temp/ - Temporary downloads
  • /opt/media-downloader/logs/ - Log files
  • /opt/media-downloader/venv/ - Virtual environment (reproducible)
  • /opt/media-downloader/.playwright/ - Playwright cache (reproducible)
  • /opt/media-downloader/debug/ - Debug files
  • *.log, *.log.* - All log files
  • *.pyc, __pycache__ - Python bytecode
  • *.db-shm, *.db-wal - SQLite temporary files
  • Swap files: *.swp, *.swo, *~

Retention Policy

  • Daily: 7 days
  • Weekly: 4 weeks
  • Monthly: 12 months
  • Yearly: 2 years

Notifications

  • Success: Disabled (runs daily, would spam)
  • Warning: Enabled (Pushover)
  • Failure: Enabled (Pushover)

Creating Version Backups

Manual Version Backup

To create a version-stamped locked backup:

cd /opt/media-downloader
./scripts/create-version-backup.sh

This will:

  1. Read version from VERSION file
  2. Create timestamp
  3. Generate backup name: {version}-{timestamp}
  4. Run backup using Backup Central
  5. Lock the backup (prevent deletion)

Example backup name:

6.0.0-20251026-143000

This matches backup-central's naming convention: {version}-{YYYYMMDD-HHMMSS}

When to Create Version Backups

Create manual version backups:

  • Before releasing a new version - Capture stable state
  • After major changes - Database schema, config structure
  • Before risky operations - Large refactors, dependency updates
  • Milestone achievements - Feature completions, bug fixes

Scheduled Backups

Daily backups run automatically:

  • Time: 00:00 (midnight)
  • Managed by: Backup Central scheduler
  • Type: Incremental (restic)
  • Not locked - Subject to retention policy

Backup Management

List All Backups

backup-central list -P profile-media-downloader

View Profile Details

backup-central profiles --info profile-media-downloader

Manual Backup

backup-central backup -P profile-media-downloader

Create Custom Named Backup

backup-central backup -P profile-media-downloader -n "before-upgrade" -l

Restore from Backup

# List snapshots
backup-central list -P profile-media-downloader

# Restore specific snapshot
backup-central restore <snapshot-id> -P profile-media-downloader -t /opt/media-downloader-restore

Lock/Unlock Backups

# Lock important backups (prevent deletion)
backup-central lock <backup-id>

# Unlock backups
backup-central unlock <backup-id>

Version Release Process

1. Update Code & Test

  • Make changes
  • Test thoroughly
  • Verify all platforms work
  • Check database operations

2. Update Version

# Edit VERSION file
echo "6.1.0" > /opt/media-downloader/VERSION

3. Update CHANGELOG

  • Document all changes in CHANGELOG.md
  • Follow existing format
  • Include:
    • New features
    • Bug fixes
    • Breaking changes
    • Upgrade notes

4. Create Version Backup

./scripts/create-version-backup.sh

5. Tag & Commit (if using git)

git add VERSION CHANGELOG.md
git commit -m "Release v6.1.0"
git tag -a v6.1.0 -m "Version 6.1.0 release"
git push && git push --tags

6. Verify Backup

backup-central list -P profile-media-downloader --limit 5

Disaster Recovery

Full System Restore

  1. Install base system

    sudo mkdir -p /opt/media-downloader

  2. Restore from backup

    backup-central restore <snapshot-id> -P profile-media-downloader -t /opt

  3. Reinstall dependencies

    cd /opt/media-downloader
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
playwright install chromium

  4. Set permissions

    sudo chown -R $USER:$USER /opt/media-downloader
chmod +x /opt/media-downloader/media-downloader.py
chmod +x /opt/media-downloader/db
chmod +x /opt/media-downloader/scripts/*.sh

  5. Verify

    /opt/media-downloader/media-downloader.py --version
./db stats

Partial Restore (Config Only)

# Restore just config directory
backup-central restore <snapshot-id> \
  -P profile-media-downloader \
  -i "/opt/media-downloader/config" \
  -t /tmp/restore

# Copy to production
sudo cp -r /tmp/restore/opt/media-downloader/config/* /opt/media-downloader/config/

Database Restore

# Restore just database
backup-central restore <snapshot-id> \
  -P profile-media-downloader \
  -i "/opt/media-downloader/database" \
  -t /tmp/restore

# Stop scheduler
sudo systemctl stop media-downloader

# Replace database
sudo cp /tmp/restore/opt/media-downloader/database/*.db /opt/media-downloader/database/

# Restart
sudo systemctl start media-downloader

Backup Verification

Verify Backup Integrity

# Check backup profile health
backup-central health

# Verify specific profile
backup-central profiles --stats profile-media-downloader

Test Restore

Periodically test restores to ensure backups are usable:

# 1. Create test restore directory
mkdir -p /tmp/media-downloader-test-restore

# 2. Restore to test location
backup-central restore latest -P profile-media-downloader -t /tmp/media-downloader-test-restore

# 3. Verify critical files exist
ls -la /tmp/media-downloader-test-restore/opt/media-downloader/config/
ls -la /tmp/media-downloader-test-restore/opt/media-downloader/database/

# 4. Check database integrity
sqlite3 /tmp/media-downloader-test-restore/opt/media-downloader/database/media_downloader.db "PRAGMA integrity_check;"

# 5. Clean up
rm -rf /tmp/media-downloader-test-restore

Troubleshooting

Backup Fails

Check destination:

ls -la /media/backups/Ubuntu/restic-repo

Check logs:

backup-central list -P profile-media-downloader
sudo journalctl -u backup-central -f

Manual test:

backup-central backup -P profile-media-downloader --dry-run

Version Script Fails

Check VERSION file:

cat /opt/media-downloader/VERSION

Verify profile exists:

backup-central profiles list | grep media-downloader

Test backup manually:

backup-central backup -P profile-media-downloader -n "test-backup"

Best Practices

Version Management

  • ✅ Update VERSION file before creating version backup
  • ✅ Always update CHANGELOG.md with version
  • ✅ Use semantic versioning (MAJOR.MINOR.PATCH)
  • ✅ Lock important release backups
  • ✅ Tag releases in git (if using version control)

Backup Strategy

  • ✅ Create version backup before major changes
  • ✅ Test restores quarterly
  • ✅ Verify backup notifications work
  • ✅ Monitor backup sizes (check for bloat)
  • ✅ Keep locked backups for major versions
  • ✅ Document any custom backup procedures

Security

  • ✅ Backups include credentials (cookies, sessions, config)
  • ✅ Ensure backup destination is secure
  • ✅ Restrict access to backup restoration
  • ✅ Consider encryption for sensitive data
  • ✅ Don't commit credentials to git

See Also

Reference in New Issue View Git Blame Copy Permalink