voicebox/docs/r2-setup.md

Cloudflare R2 Setup Guide

Overview

The CUDA binary (2.4GB) is hosted on Cloudflare R2 at downloads.voicebox.sh instead of GitHub Releases (which has a 2GB limit).

R2 Bucket Configuration

✅ Completed:

• Bucket created: voicebox
• Custom domain configured: downloads.voicebox.sh

GitHub Secrets Required

Add these secrets to your GitHub repository:

1. R2_ACCESS_KEY_ID

Your Cloudflare R2 API Access Key ID

How to get it:

1. Go to Cloudflare Dashboard → R2
2. Click "Manage R2 API Tokens"
3. Create API Token with "Object Read & Write" permissions
4. Copy the "Access Key ID"

Add to GitHub:

Repository Settings → Secrets and variables → Actions → New repository secret
Name: R2_ACCESS_KEY_ID
Value: <your-access-key-id>

2. R2_SECRET_ACCESS_KEY

Your Cloudflare R2 Secret Access Key

How to get it:

• Same process as above
• Copy the "Secret Access Key" (shown only once!)
• Store it securely

Add to GitHub:

Name: R2_SECRET_ACCESS_KEY
Value: <your-secret-access-key>

3. R2_ENDPOINT

Your Cloudflare R2 endpoint URL

Format:

https://<account-id>.r2.cloudflarestorage.com

How to find your account ID:

• Cloudflare Dashboard → R2
• Look at the URL or bucket settings
• Should be a string of letters/numbers

Add to GitHub:

Name: R2_ENDPOINT
Value: https://<your-account-id>.r2.cloudflarestorage.com

Bucket Structure

After CI uploads, the bucket will have this structure:

voicebox/
└── cuda/
    ├── v0.1.12/
    │   └── voicebox-server-cuda-x86_64-pc-windows-msvc.exe
    ├── v0.1.13/
    │   └── voicebox-server-cuda-x86_64-pc-windows-msvc.exe
    └── v0.2.0/
        └── voicebox-server-cuda-x86_64-pc-windows-msvc.exe

Public Access

Files are uploaded with --acl public-read, making them accessible at:

https://downloads.voicebox.sh/cuda/v{VERSION}/voicebox-server-cuda-x86_64-pc-windows-msvc.exe

Example:

https://downloads.voicebox.sh/cuda/v0.1.12/voicebox-server-cuda-x86_64-pc-windows-msvc.exe

Testing the Setup

Local Test Upload

Before running the CI, test uploading locally:

# Set environment variables
export AWS_ACCESS_KEY_ID="your-r2-access-key-id"
export AWS_SECRET_ACCESS_KEY="your-r2-secret-access-key"
export R2_ENDPOINT="https://your-account-id.r2.cloudflarestorage.com"

# Install AWS CLI
pip install awscli

# Test upload (use a small test file first)
echo "test" > test.txt
aws s3 cp test.txt \
  s3://voicebox/test/test.txt \
  --endpoint-url $R2_ENDPOINT \
  --acl public-read

# Verify it's accessible
curl https://downloads.voicebox.sh/test/test.txt

# If successful, try the actual CUDA binary
aws s3 cp backend/dist/voicebox-server-cuda.exe \
  s3://voicebox/cuda/v0.1.12-test/voicebox-server-cuda-x86_64-pc-windows-msvc.exe \
  --endpoint-url $R2_ENDPOINT \
  --acl public-read

Verify Upload

Check if the file is accessible:

curl -I https://downloads.voicebox.sh/cuda/v0.1.12-test/voicebox-server-cuda-x86_64-pc-windows-msvc.exe

Should return:

HTTP/2 200
content-length: 2545086396
content-type: application/x-msdownload
...

CI Workflow

The workflow now:

1. Builds CPU binary → Includes in installer
2. Builds CUDA binary → Uploads to R2
3. Release notes → Include R2 download link

CI Steps (Windows)

- name: Build CUDA Python server (Windows only)
  # Builds the CUDA binary

- name: Upload CUDA server to Cloudflare R2 (Windows only)
  env:
    AWS_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
    AWS_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
    R2_ENDPOINT: ${{ secrets.R2_ENDPOINT }}
  run: |
    aws s3 cp backend/cuda-release/voicebox-server-cuda-*.exe \
      s3://voicebox/cuda/${VERSION}/... \
      --endpoint-url $R2_ENDPOINT \
      --acl public-read

Cost Tracking

Monitor your R2 usage:

Cloudflare Dashboard → R2 → voicebox → Metrics

Expected costs (per month):

• Storage: 2.4GB × $0.015/GB = $0.036
• Egress: $0.00 (free!)
• Class A ops: ~100 × $4.50/million = $0.00

Total: ~$0.04/month (essentially free!)

Troubleshooting

Upload fails: "Access Denied"

Solution: Check API token permissions

• Must have "Object Read & Write" on the bucket
• Regenerate token if needed

File not accessible at downloads.voicebox.sh

Solution: Check custom domain configuration

• R2 Dashboard → Bucket → Settings → Custom Domains
• Ensure downloads.voicebox.sh is properly configured
• DNS may take time to propagate

"endpoint-url" not recognized

Solution: Make sure AWS CLI is updated

pip install --upgrade awscli

File uploaded but wrong permissions

Solution: Re-upload with --acl public-read

aws s3 cp ... --acl public-read

Or set bucket default permissions in R2 Dashboard.

Security Notes

API Token Permissions

✅ Recommended:

• Object Read & Write only
• No admin permissions needed
• Scoped to voicebox bucket only

❌ Avoid:

• Account-wide permissions
• Account admin access
• Worker edit permissions

Secret Rotation

Rotate API tokens every 6-12 months:

1. Create new API token
2. Update GitHub secrets
3. Verify CI still works
4. Delete old token

Maintenance

Cleaning Old Versions

Optional: Delete old CUDA binaries to save storage costs

# List all versions
aws s3 ls s3://voicebox/cuda/ \
  --endpoint-url $R2_ENDPOINT

# Delete old version
aws s3 rm s3://voicebox/cuda/v0.1.0/ \
  --recursive \
  --endpoint-url $R2_ENDPOINT

Monitoring

Set up Cloudflare notifications:

• Storage approaching limits
• Unusual traffic patterns
• High operation counts

Next Steps

1. ✅ Bucket configured
2. ⏳ Add GitHub secrets (R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_ENDPOINT)
3. ⏳ Test local upload
4. ⏳ Push branch and create test release
5. ⏳ Verify CUDA binary accessible from downloads.voicebox.sh
6. ⏳ Implement frontend download manager

---

Status: Ready for testing Cost: ~$0.04/month Bandwidth: Free (unlimited)