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
```bash
docker-compose down
```

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

### 3. Create New Directory Structure
```bash
mkdir -p downloads/permanent downloads/kept downloads/cache
```

### 4. Move Existing Files

**Move permanent downloads:**
```bash
# 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:**
```bash
if [ -d "kept" ]; then
  mv kept/* downloads/kept/ 2>/dev/null || true
  rmdir kept
fi
```

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

### 5. Update .env File
```bash
# 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
```bash
# 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
```bash
docker-compose up -d
```

### 9. Check Logs
```bash
docker-compose logs -f allstarr
```

## Rollback (If Needed)

If something goes wrong:

```bash
# 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