SUPABASE_SETUP.md

Supabase Storage Setup Guide

This document explains how to configure Supabase Storage for file uploads in InstantSplat, replacing the previous HuggingFace Hub upload functionality.

Why Supabase Storage?

The HuggingFace Hub upload has been replaced with Supabase Storage to avoid websocket dependency issues that were encountered with the supabase-py library. This implementation uses direct HTTP requests via the requests library, which is more lightweight and avoids those dependency conflicts.

Setup Instructions

1. Create a Supabase Project

1. Go to supabase.com and create a new project
2. Wait for the project to be provisioned

2. Create a Storage Bucket

1. In your Supabase dashboard, navigate to Storage
2. Click New bucket
3. Create a bucket named outputs (or any name you prefer)
4. Choose whether to make it public or private:
   • Public: Files are accessible via public URLs (recommended for this use case)
   • Private: Files require authentication to access

3. Configure Bucket Policies (if using public bucket)

For public access, ensure your bucket has appropriate policies:

1. Go to Storage > Policies

2. For the outputs bucket, add a policy for SELECT (read) operations:

   -- Allow public read access
   CREATE POLICY "Public read access"
   ON storage.objects FOR SELECT
   TO public
   USING (bucket_id = 'outputs');
   

3. Add a policy for INSERT (upload) operations:

   -- Allow authenticated uploads
   CREATE POLICY "Authenticated uploads"
   ON storage.objects FOR INSERT
   TO authenticated
   WITH CHECK (bucket_id = 'outputs');
   

4. Get Your Credentials

1. Go to Settings > API in your Supabase dashboard
2. Copy the following values:
   • Project URL: https://xxxxx.supabase.co
   • anon public key: For client-side uploads (limited permissions)
   • service_role key: For server-side uploads (full permissions)

⚠️ Important: Use the service_role key for server-side applications like this one, as it has full permissions to upload files.

5. Set Environment Variables

Set the following environment variables in your deployment environment:

export SUPABASE_URL="https://your-project-id.supabase.co"
export SUPABASE_KEY="your-service-role-key"
export SUPABASE_BUCKET="outputs"  # Optional, defaults to "outputs"

For local development, you can create a .env file:

SUPABASE_URL=https://your-project-id.supabase.co
SUPABASE_KEY=your-service-role-key
SUPABASE_BUCKET=outputs

6. Configure File Size Limits

By default, Supabase Storage has the following limits:

• Free tier: Up to 50 MB per file
• Pro tier: Up to 5 GB per file (standard uploads)
• Pro tier with resumable uploads: Up to 50 GB per file

To increase file size limits:

1. Go to Storage > Settings
2. Set the Global file size limit
3. Optionally set per-bucket limits

For files larger than 6 MB, the implementation includes:

• ✅ Automatic retry logic with exponential backoff
• ✅ 10-minute timeout for large file uploads
• ✅ Direct storage hostname usage for better performance

Implementation Details

The new implementation uses the Supabase Storage REST API directly:

Endpoint Structure

POST https://{project-id}.storage.supabase.co/storage/v1/object/{bucket}/{path}

Headers

Authorization: Bearer {service_role_key}
apikey: {service_role_key}
Content-Type: {mime-type}
x-upsert: true

Features

• Direct HTTP uploads: No Python library dependencies beyond requests
• Retry logic: Automatic retries with exponential backoff for failed uploads
• Large file support: Tested with files up to several hundred MB
• Performance optimization: Uses direct storage hostname for better upload speeds
• Auto content-type detection: Automatically sets MIME types for .ply, .glb, and .mp4 files
• Upsert support: Automatically overwrites existing files with the same name

Testing

To test the upload functionality locally:

from app import upload_to_supabase_storage

url = upload_to_supabase_storage(
    file_path="path/to/your/file.ply",
    remote_path="test/file.ply",
    supabase_url=os.environ.get("SUPABASE_URL"),
    supabase_key=os.environ.get("SUPABASE_KEY"),
    bucket_name="outputs"
)

print(f"Uploaded to: {url}")

Troubleshooting

Upload fails with 401 Unauthorized

• Check that SUPABASE_KEY is set correctly
• Ensure you're using the service_role key, not the anon key
• Verify the key hasn't been rotated or revoked

Upload fails with 403 Forbidden

• Check bucket policies allow INSERT operations
• Verify the bucket exists and is spelled correctly
• Ensure the service role key has appropriate permissions

Upload times out

• Check your network connection
• Verify file size is within limits
• Consider increasing the timeout parameter in the upload function

Files upload but aren't accessible

• If using a public bucket, ensure SELECT policies are configured
• Check that the bucket is set to public in Storage settings
• Verify the public URL format matches your project

Migration Notes

Changes from HuggingFace Hub

Aspect	HF Hub	Supabase Storage
Authentication	HF_TOKEN	SUPABASE_URL + SUPABASE_KEY
Bucket/Repo	SPACE_REPO_ID	SUPABASE_BUCKET
URL format	huggingface.co/spaces/...	{project}.storage.supabase.co/...
Library	huggingface_hub	requests (standard library)

Environment Variable Migration

Old (HF Hub):

HF_TOKEN=hf_xxx

New (Supabase):

SUPABASE_URL=https://xxx.supabase.co
SUPABASE_KEY=eyJxxx
SUPABASE_BUCKET=outputs

Additional Resources

• Supabase Storage Documentation
• Storage REST API Reference
• File Upload Best Practices