# Storage Provider Setup Guide

AfricanMusic supports two storage providers for audio files, images, and other media:

## 1. Vercel Blob Storage (Default)

### Setup
- **No configuration required** - automatically enabled
- Integrated with your Vercel deployment
- Suitable for most use cases

### Features
- Fast CDN delivery
- Automatic HTTPS
- Pay-as-you-go pricing

---

## 2. Cloudflare R2 Storage

### Why use Cloudflare R2?
- **Zero egress fees** - no charges for bandwidth
- S3-compatible API
- Global edge network
- Better for high-traffic apps

### Setup Steps

#### 1. Create Cloudflare R2 Bucket

1. Log in to [Cloudflare Dashboard](https://dash.cloudflare.com)
2. Go to **R2** in the sidebar
3. Click **Create Bucket**
4. Name your bucket (e.g., `africanmusic-storage`)
5. Choose a location close to your users

#### 2. Create API Tokens

1. In R2 dashboard, go to **Manage R2 API Tokens**
2. Click **Create API Token**
3. Select **Read & Write** permissions
4. Copy the **Access Key ID** and **Secret Access Key**

#### 3. Configure CORS for Browser Playback

**IMPORTANT:** To play audio files directly in the browser, you must configure CORS on your R2 bucket.

1. Go to your R2 bucket settings
2. Click on **CORS Policy**
3. Add the following CORS configuration:

```json
[
  {
    "AllowedOrigins": ["*"],
    "AllowedMethods": ["GET", "HEAD"],
    "AllowedHeaders": ["Range", "Content-Type"],
    "ExposeHeaders": ["Content-Length", "Content-Range"],
    "MaxAgeSeconds": 3600
  }
]
```

**OR** use the Cloudflare dashboard:
- **Allowed Origins**: `*` (or your specific domain)
- **Allowed Methods**: `GET`, `HEAD`
- **Allowed Headers**: `Range`, `Content-Type`
- **Max Age**: `3600`

**Note:** If CORS is not configured, the app will automatically use a proxy endpoint to serve audio files.

#### 4. Configure Public Access (Optional but Recommended)

For public CDN access:

1. Go to your bucket settings
2. Enable **Public Access**
3. Set up a custom domain (e.g., `cdn.africanmusic.online`)
4. Copy the public URL

#### 5. Configure in AfricanMusic

1. Log in as **admin**
2. Go to **Admin Panel** → **Stockage**
3. Select **Cloudflare R2**
4. Enter the following:
   - **Account ID**: Found in R2 dashboard
   - **Access Key ID**: From step 2
   - **Secret Access Key**: From step 2
   - **Bucket Name**: Your bucket name (e.g., `africanmusic-storage`)
   - **Public URL** (optional): Your custom CDN domain
5. Click **Save**

#### 6. Test the Configuration

1. Try uploading a track or image
2. Check the console logs to confirm files are uploading to R2
3. Verify the files are accessible via the public URL

---

## Storage Provider Comparison

| Feature | Vercel Blob | Cloudflare R2 |
|---------|-------------|---------------|
| **Setup** | Automatic | Manual config required |
| **Bandwidth fees** | Yes | No (zero egress) |
| **Storage cost** | $0.15/GB/month | $0.015/GB/month |
| **Global CDN** | Yes | Yes |
| **Best for** | Quick start | High traffic apps |

---

## Migration Between Providers

### From Vercel Blob to Cloudflare R2

1. Configure Cloudflare R2 in admin settings
2. New uploads will automatically use R2
3. Existing files remain on Vercel Blob (still accessible)
4. Optional: Manually migrate old files using admin tools

### From Cloudflare R2 to Vercel Blob

1. Switch to Vercel Blob in admin settings
2. New uploads use Vercel Blob
3. Old R2 files remain accessible

---

## Troubleshooting

### Audio playback fails with "Format error"
- **Cause**: CORS not configured on R2 bucket
- **Solution**: Follow step 3 above to configure CORS
- **Workaround**: Audio will automatically use proxy endpoint if direct access fails

### R2 uploads fail
- Verify API credentials are correct
- Check bucket name matches exactly
- Ensure bucket has correct permissions

### Files not accessible
- Verify public access is enabled
- Check custom domain DNS settings
- Confirm CORS settings allow your domain

### Fallback to Vercel Blob
- If R2 upload fails, system automatically falls back to Vercel Blob
- Check console logs for error details

---

## Environment Variables

The storage configuration is stored in the database (`system_settings` table), not in environment variables. This allows admins to switch providers without redeploying.

Required settings:
- `storage_provider` - Either `vercel-blob` or `cloudflare-r2`
- `cloudflare_r2_account_id`
- `cloudflare_r2_access_key`
- `cloudflare_r2_secret_key`
- `cloudflare_r2_bucket_name`
- `cloudflare_r2_public_url` (optional)
