259 lines
6.8 KiB
Markdown
259 lines
6.8 KiB
Markdown
# 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`**
|
|
```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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
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.
|