Supabase Storage for profile photos in Next.js
Supabase configures every project with Storage for managing large files like photos and videos. Create an upload widget component to allow users to upload profile photos.
storage rules
20 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Direct file copy to volumes/storage/ does not work for self-hosted Storage
Direct file copy by downloading files and placing them into volumes/storage/ does not work. Self-hosted Storage uses an internal file structure that differs from what you get when downloading files from the platform. Use the S3 protocol to transfer objects so that Storage creates the correct metadata records.
Query storage buckets on platform database
To list buckets on your platform database, connect and run: select id, name, public from storage.buckets order by name;
Create matching buckets on self-hosted instance
Buckets must exist on the destination before copying objects. Connect to the self-hosted database and run: insert into storage.buckets (id, name, public) values ('your-storage-bucket', 'your-storage-bucket', false) on conflict (id) do nothing; Repeat for each bucket, setting public to true or false as appropriate. If you already restored your platform database to self-hosted using the restore guide, bucket definitions are already present.
S3 protocol does not auto-create buckets on copy
If rclone reports that a bucket doesn't exist on the self-hosted side, create it first manually. The S3 protocol does not auto-create buckets on copy.
S3-compatible provider backend configuration
To use an S3-compatible provider (such as Cloudflare R2) as the Storage backend, configure: STORAGE_BACKEND as 's3', GLOBAL_S3_BUCKET with your bucket name, GLOBAL_S3_ENDPOINT with your provider's endpoint URL, GLOBAL_S3_FORCE_PATH_STYLE as 'true', AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and REGION. Replace these values with those provided by your S3-compatible provider.
S3 protocol endpoint configuration for self-hosted Storage
The S3 protocol endpoint is exposed at `/storage/v1/s3` and allows standard S3 tools like rclone and AWS CLI to interact with your Storage instance. It works with any storage backend, including the default file-based storage, and does not require an S3 backend to be configured first. The Supabase REST API and SDK do not use the S3 protocol. To enable it, configure REGION, S3_PROTOCOL_ACCESS_KEY_ID, and S3_PROTOCOL_ACCESS_KEY_SECRET in the docker-compose.yml storage service environment variables.
S3 backend configuration variables for self-hosted Storage
S3 backend configuration for Storage in docker-compose.yml requires these environment variables in the storage service: STORAGE_BACKEND (set to 's3'), GLOBAL_S3_BUCKET (your-s3-bucket-or-dirname), GLOBAL_S3_ENDPOINT (https://your-s3-endpoint), GLOBAL_S3_PROTOCOL (https), GLOBAL_S3_FORCE_PATH_STYLE ('true'), AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and REGION. These variables define how Storage keeps data on an S3-compatible service instead of the default local filesystem.
Testing S3 protocol endpoint with AWS CLI
To test the S3 protocol endpoint with AWS CLI, run: AWS_ACCESS_KEY_ID=$S3_PROTOCOL_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY=$S3_PROTOCOL_ACCESS_KEY_SECRET aws s3 ls --endpoint-url http://localhost:8000/storage/v1/s3 --region $REGION s3://your-storage-bucket. Load environment variables from .env file before running the command.
Testing S3 protocol endpoint with rclone
To test the S3 protocol endpoint with rclone, run: rclone ls --s3-endpoint http://localhost:8000/storage/v1/s3 --s3-region $REGION --s3-provider Other --s3-access-key-id "$S3_PROTOCOL_ACCESS_KEY_ID" --s3-secret-access-key "$S3_PROTOCOL_ACCESS_KEY_SECRET" :s3:your-storage-bucket. Load environment variables from .env file before running the command. Use 'aws login' and 'rclone config' for persistent configuration.
AWS S3 backend configuration requirements
For AWS S3 backend, configure STORAGE_BACKEND as 's3', GLOBAL_S3_BUCKET with your AWS bucket name, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and REGION with your AWS region. Do not set GLOBAL_S3_ENDPOINT or GLOBAL_S3_FORCE_PATH_STYLE for AWS S3, as the Storage S3 client automatically resolves the endpoint from the region and uses virtual-hosted-style URLs. These variables are only needed for non-AWS S3-compatible providers.
RustFS S3-compatible backend setup
To enable RustFS container as an S3-compatible API for Storage backend in self-hosted Supabase, run: sh run.sh config add rustfs, then sh run.sh start. Review the Storage section in your .env file for related configuration options.
MinIO S3-compatible backend setup
To enable MinIO container as an S3-compatible API for Storage backend in self-hosted Supabase, run: sh run.sh config add s3, then sh run.sh start. MinIO no longer publishes open source Docker images; the configuration uses images built by Chainguard (cgr.dev/chainguard/minio). For new deployments, consider using RustFS instead. Review the Storage section in your .env file for related configuration options.
Session token authentication for S3 storage
You can authenticate to Supabase's S3-compatible storage using a user's JWT to enforce Row-Level Security (RLS) across S3 operations. Provide region (REGION env variable), access_key_id (STORAGE_TENANT_ID env variable), secret_access_key (ANON_KEY env variable), and session_token (a valid user JWT). All operations with a session token are scoped to the authenticated user, and any RLS policies defined in the storage schema will be applied.
Session token S3 client example with aws-sdk
Example using aws-sdk to authenticate S3 with a session token: const client = new S3Client({ forcePathStyle: true, region: 'stub', // REGION in .env, endpoint: 'http://<your-domain>/storage/v1/s3', credentials: { accessKeyId: 'stub', // STORAGE_TENANT_ID in .env, secretAccessKey: 'your-anon-key', // ANON_KEY in .env, sessionToken: session.access_token } }). First get the session with: const { data: { session } } = await supabase.auth.getSession()
Signature mismatch errors troubleshooting
If you see SignatureDoesNotMatch errors, verify that REGION, S3_PROTOCOL_ACCESS_KEY_ID, and S3_PROTOCOL_ACCESS_KEY_SECRET in your .env file match what your S3 client is using. With a custom reverse proxy using new API keys configuration, requests to Storage should be forwarded to the API gateway. If using legacy API keys and proxying directly to Storage, ensure your proxy sets the X-Forwarded-Prefix header to /storage/v1 for correct signed URL generation. In both cases, STORAGE_PUBLIC_URL must be set properly in docker-compose.yml.
TUS upload errors on Cloudflare R2
If resumable (TUS) uploads fail with HTTP 500 and a message about x-amz-tagging when using Cloudflare R2, add TUS_ALLOW_S3_TAGS: "false" to the storage service environment. Cloudflare R2 does not implement this S3 feature.
Permission denied on S3 storage uploads
Setting a bucket to 'Public' only allows unauthenticated downloads. Uploads are always blocked unless you create an RLS policy on the storage.objects table. Create a policy that allows INSERT for the appropriate roles via Storage > Files > Policies in Studio.
Upload URLs pointing to localhost issue
If uploads from a browser fail with CORS or mixed content errors, check that SUPABASE_PUBLIC_URL in your .env file matches your actual domain and protocol, not http://localhost:8000.
S3 Storage configuration in self-hosted Supabase
By default, self-hosted Storage stores all files locally on server filesystem via bind mount. You can connect Storage to S3-compatible backend (AWS S3, RustFS, MinIO, Cloudflare R2), enable S3 protocol endpoint for tools like rclone, or both. These are independent features.