Thumbnail System Migration

📸 Thumbnail System Migration

🌟 Overview

Starting with version 3.2.0, Calibre-Web-Automated uses an improved thumbnail storage system:

• 🎯 Deterministic naming: book_<id>_r<resolution>.webp instead of UUID-based names
• 🖼️ WebP format: Better compression and quality than JPEG
• 📁 Flat directory: All thumbnails stored in /config/thumbnails/ directly (no subdirectories)
• 🔄 Automatic migration: Old thumbnails are cleaned up automatically on startup

🔧 What Happens During Migration

🆕 For New Installations

• ✅ No migration needed
• 🚀 Thumbnails are generated in the new format from the start

📦 For Existing Installations

On the first startup after updating, the system will:

1. 🔍 Detect old thumbnail structure (hex subdirectories like 00/, 01/, bo/, etc.)
2. 🗃️ Clear old database entries to ensure clean migration
3. 🗂️ Remove old files and subdirectories from /config/thumbnails/
4. 📝 Log the migration process for transparency
5. ✅ Mark migration as completed to prevent re-running

📄 Example Migration Log

INFO: Thumbnail migration: Found 158 old subdirectories, starting migration
INFO: Thumbnail migration: Cleared 255 old database entries  
INFO: Thumbnail migration: Removed 255 old files and 158 subdirectories
INFO: Thumbnail migration: Complete. Thumbnails will be regenerated automatically as needed.

✨ After Migration

• 🔄 Thumbnails will be regenerated automatically as books are accessed
• 🖱️ You can manually trigger regeneration via Admin → "Refresh Thumbnail Cache"
• 📂 New structure: /config/thumbnails/book_123_r2.webp (directly in folder)
• 📁 Old structure: /config/thumbnails/bo/book_123_r2.webp (in subdirectories) ← removed

🎉 Benefits

1. 🐛 Easier debugging: Filenames directly show book ID and resolution
2. ⚡ Better performance: No filesystem overhead from empty subdirectories
3. 🧹 Simpler maintenance: All files in one location
4. 🖼️ Improved quality: WebP format provides better compression
5. 🔮 Future-proof: Deterministic naming supports advanced features

⏪ Rollback (If Needed)

If you need to rollback before migration completes:

1. 🛑 Stop the CWA container
2. 💾 Restore /config/thumbnails/ from backup
3. 🔄 Restart with the previous CWA version

⚠️ Note: After successful migration, rollback is not recommended as old thumbnails are permanently removed.

🛠️ Troubleshooting

❌ Migration Fails

• 📋 Check logs for specific error messages
• 🔐 Ensure /config/thumbnails/ is writable by the abc user
• 🔄 Migration will be retried on next startup if it fails

🔒 Permission Issues

docker exec -it cwa-dev chown -R abc:abc /config/thumbnails
docker exec -it cwa-dev chmod 755 /config/thumbnails

🔧 Force Re-migration (Development Only)

If you need to test migration again:

-- Connect to app.db and remove migration marker
DELETE FROM settings WHERE mail_server = 'thumbnail_flat_structure_migration';

⚡ Performance Impact

• ⏱️ Migration time: ~1-5 seconds for typical libraries (100-1000 books)
• 💽 Disk space: Temporarily ~2x during migration, then reduced due to WebP compression
• 🚫 No downtime: Migration runs during normal startup process
• 🛡️ Graceful failure: App continues working even if migration fails