BucketBuddy LogoBucketBuddy
HomeDocumentationCore Concepts

Core Concepts

Understanding these core concepts will help you get the most out of Bucket Buddy.

Sites (Buckets)

In Bucket Buddy, a Site represents a project or application that needs S3 storage. Each site you create automatically gets:

  • A unique identifier
  • S3-compatible credentials (access key and secret key)
  • A private bucket
  • Connection endpoints for your application

Site Properties

Each site has the following properties:

  • Name: A friendly identifier for your site (e.g., "my-blog", "photo-app")
  • Color: A visual identifier to quickly distinguish between sites
  • Local Path (optional): Path to a local project for integration
  • Credentials: Unique S3 access key and secret key

Providers: Private vs Public Buckets

Bucket Buddy gives each site a private bucket by default. Due to providers handling public access to files differently you are asked to select a provider type when setting up a new site. Right now we support two provider types and will add more if requested.

Generic Provider

The Generic Provider uses the standard S3 protocol and is compatible with Amazon S3, MinIO, and other S3-compatible services.

How Public Access Works:

  • Both private and public files are stored in the same bucket
  • Public files are marked with a public-read ACL header, making them accessible without authentication
  • Private files use the default private ACL, requiring signed requests for access

This approach is the traditional S3 method and works well with most S3-compatible services.

Cloudflare R2 provider

The Cloudflare R2 Provider is specifically designed for Cloudflare's R2 storage service, which handles public access differently than standard S3.

How Public Access Works:

  • Creates two separate buckets for each site:
    • Private bucket: your-site-name - requires authentication for all access
    • Public bucket: your-site-name-public - allows public read access without authentication
  • Public files are automatically routed to the public bucket
  • Private files stay in the private bucket

This two-bucket approach aligns with R2's public bucket configuration, where you enable public access at the bucket level rather than using ACL headers.

Local Project Integration

If your local project is written with PHP, uses composer and/or an .env file e.g. Laravel, Bucket Buddy can sync with the project making it easy to use S3 storage during development

We will be adding more support for additional ecosystems as we grow

How It Works

When you link a site to a project, Bucket Buddy can automatically set everything up for you:

  1. Detects Your Project: Bucket Buddy recognizes the application uses composer and/or has a .env file
  2. Checks S3 Support: Verifies if your project already has S3 configured
  3. Automatic Setup (with your permission):
    • Installs the required S3 package in your Laravel project
    • Updates your project's .env file with the S3 credentials

Laravel Herd Integration

If you're using Laravel Herd, Bucket Buddy makes integration even easier:

  • Auto-Discovery: Bucket Buddy automatically finds all your Herd projects
  • Simple Import: Import any Herd project with a few clicks
  • Smart Detection: Reads your project name and settings automatically
  • Status Checking: Shows which projects are already configured

Don't have Laravel Herd? No problem! You can still manually link any project by browsing to its folder when creating a site.

How Bucket Buddy Works

What You Can Do

With Bucket Buddy, you can:

  • Upload Files: Add files through the app or from your application
  • Download Files: Retrieve files through the app or programmatically
  • Organize Files: Create folders and manage your file structure
  • Delete Files: Remove files you no longer need
  • Copy/Move Files: Reorganize your storage as needed
  • Browse Files: View all files in an easy-to-use interface

Works With

Bucket Buddy is compatible with:

  • Laravel: Full support for Laravel's Storage system
  • PHP Applications: Any app using the AWS SDK for PHP
  • Other S3 Clients: Most libraries and tools that support custom S3 endpoints

Where Is Everything Stored?

Bucket Buddy stores all your data locally on your computer for complete privacy and control.

Your Files

All uploaded files are stored in folders on your computer. Each site has its own dedicated folder with separate private and public bucket storage if needed. The folder structure you create in Bucket Buddy matches how files are organized on your disk.

Privacy and Security

Designed for Local Use

Bucket Buddy is designed for local development only. This means:

  • Everything runs on your computer - no cloud services involved
  • Your files never leave your machine unless you set up a remote connection
  • The S3 server only listens on your local computer (localhost)
  • Nobody on the internet can access your files

Important: Don't try to use Bucket Buddy as a production file server. It's meant for development and testing only.

Next Steps

Now that you understand the core concepts: