allstarr/MIGRATION.md

Migration Guide: Reorganizing Download Structure

This guide is for upgrading from the old download structure to the new unified structure.

Old Structure

./downloads/     # Permanent downloads
./kept/          # Favorited tracks  
./cache/         # Cached tracks

New Structure

./downloads/
├── permanent/   # Permanent downloads
├── kept/        # Favorited tracks
└── cache/       # Cached tracks

Migration Steps

1. Stop the Container

docker-compose down

2. Backup Your Data (Recommended)

# Create a backup
tar -czf allstarr-backup-$(date +%Y%m%d).tar.gz downloads/ kept/ cache/ 2>/dev/null

3. Create New Directory Structure

mkdir -p downloads/permanent downloads/kept downloads/cache

4. Move Existing Files

Move permanent downloads:

# If you have files directly in downloads/
if [ -d "downloads" ] && [ ! -d "downloads/permanent" ]; then
  # Move all files/folders except the new subdirectories
  find downloads/ -maxdepth 1 -mindepth 1 ! -name 'permanent' ! -name 'kept' ! -name 'cache' ! -name 'playlists' -exec mv {} downloads/permanent/ \;
fi

# Move playlists folder if it exists
if [ -d "downloads/playlists" ]; then
  mv downloads/playlists downloads/permanent/
fi

Move kept files:

if [ -d "kept" ]; then
  mv kept/* downloads/kept/ 2>/dev/null || true
  rmdir kept
fi

Move cache files:

if [ -d "cache" ]; then
  mv cache/* downloads/cache/ 2>/dev/null || true
  rmdir cache
fi

5. Update .env File

# Remove old variables
sed -i.bak '/^KEPT_PATH=/d' .env
sed -i.bak '/^CACHE_PATH=/d' .env

# Ensure DOWNLOAD_PATH is set correctly
if ! grep -q "^DOWNLOAD_PATH=" .env; then
  echo "DOWNLOAD_PATH=./downloads" >> .env
else
  sed -i.bak 's|^DOWNLOAD_PATH=.*|DOWNLOAD_PATH=./downloads|' .env
fi

6. Update Media Server Library Paths

For Jellyfin:

1. Go to Dashboard → Libraries
2. Edit your Music library
3. Update the folder path from downloads to downloads/permanent
4. Scan library

For Navidrome/Subsonic:

1. Update your music folder configuration
2. Change from downloads to downloads/permanent
3. Restart and rescan

7. Verify Migration

# Check the new structure
ls -la downloads/
ls -la downloads/permanent/
ls -la downloads/kept/
ls -la downloads/cache/

# Count files in each directory
echo "Permanent: $(find downloads/permanent -type f | wc -l) files"
echo "Kept: $(find downloads/kept -type f | wc -l) files"
echo "Cache: $(find downloads/cache -type f | wc -l) files"

8. Start the Container

docker-compose up -d

9. Check Logs

docker-compose logs -f allstarr

Rollback (If Needed)

If something goes wrong:

# Stop container
docker-compose down

# Restore from backup
tar -xzf allstarr-backup-YYYYMMDD.tar.gz

# Restore old .env
mv .env.bak .env

# Start container
docker-compose up -d

Verification Checklist

• All files moved to new structure
• Old directories removed or empty
• .env file updated
• Media server library paths updated
• Container starts without errors
• Can play existing tracks
• New downloads go to correct folders
• Favoriting external tracks works
• Cache cleanup works

Notes

• The migration preserves all your existing files
• Playlists (.m3u files) are moved to downloads/permanent/playlists/
• Relative paths in M3U files should still work
• If you have a lot of files, the migration may take a few minutes
• The backup is optional but highly recommended