rekordbox-viewer/WEBDAV_INTEGRATION.md

WebDAV Integration for Rekordbox Reader

This document describes the WebDAV integration that allows Rekordbox Reader to work with self-hosted storage solutions like Nextcloud and ownCloud.

🎯 Overview

The application now supports two storage providers:

• S3-Compatible Storage (AWS S3, MinIO, etc.)
• WebDAV (Nextcloud, ownCloud, etc.)

Users can choose between these providers in the Storage Configuration page.

🏗️ Architecture

Storage Provider Abstraction

The system uses a provider abstraction pattern:

StorageProvider Interface
├── S3Service (implements StorageProvider)
└── WebDAVService (implements StorageProvider)

Key Components

1. StorageProvider Interface (src/services/storageProvider.ts)

   • Defines common operations for all storage providers
   • Factory pattern for creating providers
   • Configuration loading and validation

2. WebDAVService (src/services/webdavService.ts)

   • Implements WebDAV operations using the webdav npm package
   • Supports Nextcloud, ownCloud, and other WebDAV-compatible servers
   • Handles file upload, download, listing, and deletion

3. Updated Configuration System

   • New /api/config/storage endpoints
   • Support for both S3 and WebDAV configuration
   • Backward compatibility with existing S3 configuration

4. Frontend Storage Configuration

   • Provider selection (S3 vs WebDAV)
   • Dynamic form fields based on selected provider
   • Connection testing for both providers

🚀 Setup Instructions

1. Backend Configuration

The backend automatically detects the storage provider from the configuration file:

File: storage-config.json

{
  "provider": "webdav",
  "url": "https://your-nextcloud.com/remote.php/dav/files/username/",
  "username": "your-username",
  "password": "your-password-or-app-password",
  "basePath": "/music-files"
}

2. Environment Variables

You can also configure WebDAV using environment variables:

STORAGE_PROVIDER=webdav
WEBDAV_URL=https://your-nextcloud.com/remote.php/dav/files/username/
WEBDAV_USERNAME=your-username
WEBDAV_PASSWORD=your-password-or-app-password
WEBDAV_BASE_PATH=/music-files

3. Frontend Configuration

1. Navigate to Configuration → Storage Configuration
2. Select WebDAV as the storage provider
3. Fill in your WebDAV server details:
   • URL: Your Nextcloud/ownCloud WebDAV URL
   • Username: Your account username
   • Password: Your password or app password
   • Base Path: Optional subfolder for music files
4. Click Test Connection to verify
5. Click Save Configuration to apply

🔧 Nextcloud Setup

1. Enable WebDAV

WebDAV is enabled by default in Nextcloud. You can verify this in:

• Settings → Administration → Basic settings

2. Create App Password (Recommended)

For better security, create an app password:

1. Go to Settings → Personal → Security
2. Scroll down to App passwords
3. Create a new app password for "Rekordbox Reader"
4. Use this password instead of your main password

3. Get WebDAV URL

Your WebDAV URL follows this pattern:

https://your-nextcloud.com/remote.php/dav/files/username/

Replace:

• your-nextcloud.com with your Nextcloud domain
• username with your Nextcloud username

4. Create Music Folder (Optional)

You can create a dedicated folder for music files:

1. In Nextcloud, create a folder called music-files
2. Set this as the basePath in the configuration

🔧 ownCloud Setup

The setup is similar to Nextcloud:

1. Enable WebDAV in ownCloud settings
2. Create an app password for security
3. Use the WebDAV URL: https://your-owncloud.com/remote.php/dav/files/username/
4. Configure the same way as Nextcloud

🧪 Testing

Backend Test

Run the WebDAV test script:

cd packages/backend
node test-webdav.js

Make sure to update the configuration in the test file first.

Frontend Test

1. Go to Configuration → Storage Configuration
2. Select WebDAV provider
3. Enter your WebDAV details
4. Click Test Connection
5. Verify the connection is successful

📁 File Operations

The WebDAV service supports all standard file operations:

• Upload: Upload music files to WebDAV storage
• Download: Download files for playback
• List: List all files and folders
• Delete: Remove files from storage
• Metadata: Get file information
• Streaming: Generate streaming URLs

🔒 Security Considerations

1. Use App Passwords: Don't use your main Nextcloud/ownCloud password
2. HTTPS Only: Always use HTTPS URLs for WebDAV connections
3. Base Path: Use a dedicated folder for music files
4. Permissions: Ensure the WebDAV user has appropriate permissions

🐛 Troubleshooting

Common Issues

1. Connection Failed

   • Verify the WebDAV URL is correct
   • Check username and password
   • Ensure WebDAV is enabled on your server

2. Permission Denied

   • Check if the user has write permissions
   • Verify the base path exists and is accessible

3. SSL/TLS Errors

   • Ensure you're using HTTPS
   • Check if the SSL certificate is valid

4. File Upload Fails

   • Check available storage space
   • Verify file permissions
   • Ensure the file format is supported

Debug Mode

Enable debug logging by setting:

DEBUG=webdav:*

🔄 Migration from S3

If you're migrating from S3 to WebDAV:

1. Export your current configuration
2. Set up WebDAV storage
3. Update the configuration to use WebDAV
4. The application will automatically use the new storage provider

📊 Performance

WebDAV performance depends on:

• Network latency to your server
• Server performance and storage type
• File sizes and concurrent operations

For best performance:

• Use a local or fast Nextcloud/ownCloud instance
• Consider using SSD storage
• Optimize your network connection

🎵 Supported File Formats

The WebDAV integration supports all audio formats supported by the application:

• MP3
• WAV
• FLAC
• M4A
• AAC
• OGG
• OPUS
• WMA

📝 API Endpoints

Storage Configuration

• GET /api/config/storage - Get current storage configuration
• POST /api/config/storage - Save storage configuration
• POST /api/config/storage/test - Test storage connection

Legacy S3 Endpoints

The following endpoints are still available for backward compatibility:

• GET /api/config/s3 - Get S3 configuration
• POST /api/config/s3 - Save S3 configuration
• POST /api/config/s3/test - Test S3 connection

🤝 Contributing

When adding new storage providers:

1. Implement the StorageProvider interface
2. Add the provider to StorageProviderFactory
3. Update the frontend configuration UI
4. Add appropriate tests
5. Update this documentation

📄 License

This WebDAV integration follows the same license as the main Rekordbox Reader project.