BucketBuddy LogoBucketBuddy
HomeDocumentationSite Management

Site Management

Learn how to create, import, configure, and manage your S3 sites in Bucket Buddy.

Creating Sites

There are two ways to add a site in Bucket Buddy: Create (for new or non-Herd projects) and Import (for Laravel Herd projects). Both follow a simple 2-step process.

Create a Site

Use this option when you want to create a new site without linking specifically to a project or link to a project that's not managed by Laravel Herd.

Step 1: Site Setup

  1. Click the "Create Site" button in the sidebar
  2. Or press Cmd+N (Mac) / Ctrl+N (Windows/Linux)
  3. Fill in the required details:
    • Name: Enter a unique name (e.g., "My Blog", "Photo App")
    • Provider: Select your storage provider
    • Local Project Path (optional): Enter the full path to your project
      /Users/username/Sites/photo-app
    • Color: Choose a color to identify your site

Two ways to proceed from here:

  • If you provided a Local Project Path: Click "Next" to proceed to Step 2
  • If you left the path empty: Click "Create" to create the site immediately (skips Step 2)

Step 2: Auto-Configure Options

This step only appears if you provided a local project path in Step 1.

Choose which configuration tasks Bucket Buddy should handle automatically:

  • ✅ Install S3 Package: Runs composer require league/flysystem-aws-s3-v3

    • Skips if the package is already installed
    • You'll see a notification when complete
    • Only available if composer is used in the project

  • ✅ Set ENV variables: Updates your project's .env file

    • Preserves your existing settings (comments them out)
    • Adds new credentials in a clearly marked section
    • Only available if your project has an existing .env file

Recommendation: Keep both checkboxes enabled for a completely automatic setup!

Click "Create" to finish.

Import a Site

Use this option to import existing projects managed by Laravel Herd.

How Auto-detection Works

Bucket Buddy automatically scans for Laravel Herd sites in:

  • Parked directories: Directories you've parked with Herd
  • Linked sites: Individual sites you've linked with Herd

For each detected site, Bucket Buddy checks:

  • Project name (from .env)
  • If S3 packages are already installed
  • If S3 is already configured

Note: To improve performance, Bucket Buddy caches detected sites for 1 hour. If you've added a new project to Herd or update its name in .env:

  • Hit the refresh button in the Import modal

Step 1: Select Site

  1. Click "Import Site" in the sidebar
  2. Or press Cmd+I (Mac) / Ctrl+I (Windows/Linux)
  3. Browse the list of detected Laravel Herd sites
  4. Click on a site to select it
  5. Review the detected information:
    • Project name
    • Project path
    • Current S3 package status
    • Current S3 configuration status
  6. Click "Next" to proceed to Step 2

Step 2: Configure Import

Customize the import settings:

  • Color: Choose a color to identify your site
  • Provider: Confirm the storage provider
  • Auto-Configure Options:
    • ✅ Install S3 Package: Only appears if the package isn't installed
    • ✅ Set ENV variables: Only appears if a .env exists

Recommendation: Keep the auto-configure checkboxes enabled to let Bucket Buddy handle everything!

Click "Import" to finish.

Manual Configuration

If you created a site without auto-configuration, or prefer to configure your project manually, follow these steps:

Step 1: Install the S3 Package

If your project is PHP and using composer install the below package (opinionated, can be any s3 package, but most recognised):

bash
composer require league/flysystem-aws-s3-v3

Step 2: Get Your Credentials

  1. Click on your site in the Bucket Buddy sidebar
  2. Click the Settings or Gear icon
  3. View the Connection Settings section

Step 3: Update your project

Add these settings to your project's configuration setup:

env
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_DEFAULT_REGION=local
AWS_BUCKET=your-site-name
AWS_ENDPOINT=http://s3.localhost:9876
AWS_USE_PATH_STYLE_ENDPOINT=false

Bucket naming

Bucket Buddy provides different bucket names if using the Cloudflare R2 provider:

Private Bucket:

Bucket: [site-name]

Public Bucket:

Bucket: [site-name]-public

You will see this in the UI of the public bucket as well.

Deleting Sites

When you no longer need a site, you can delete it. It will delete all the uploaded files from your filesystem.

Deleting a Site

Steps:

  1. Click on the site you want to delete
  2. Go to Site Settings
  3. Scroll to the Danger Zone
  4. Click "Delete Site"
  5. Confirm the deletion

Next Steps