BucketBuddy LogoBucketBuddy
HomeDocumentationGetting Started

Getting Started

Welcome to Bucket Buddy! This guide will help you install and set up your local S3 server in minutes.

System Requirements

Before you install Bucket Buddy, ensure your system meets the following requirements:

  • macOS: 12 or later
  • Windows: Version 10 or later
  • Linux: Ubuntu 20.04+, Fedora 35+, or equivalent
  • Disk Space: At least 200MB for the application (plus space for your files)
  • Optional: Laravel Herd for automatic Laravel project integration

Download Bucket Buddy

Download the latest version of Bucket Buddy for your operating system:

  • macOS: Download the DMG file
  • Windows: Download the installer (EXE)
  • Linux: Download the AppImage or DEB package

Visit justtom.me/account to download the latest version for your OS after purchasing.

justtom.me is my personal website where I manage my customers and their subscriptions/purchases.

Installation

macOS Installation

  1. Open the downloaded DMG file
  2. Drag Bucket Buddy to your Applications folder
  3. Open your Applications folder
  4. Double-click Bucket Buddy to launch
  5. If you see a security warning, go to System Settings > Privacy & Security and click Open Anyway

Windows Installation

  1. Double-click the downloaded installer (EXE)
  2. Follow the installation wizard
  3. Click Finish when complete
  4. Launch Bucket Buddy from your Start Menu or Desktop shortcut

Linux Installation

AppImage:

  1. Make the file executable: Right-click > Properties > Permissions > "Allow executing file as program"
  2. Double-click to run

DEB Package:

  1. Double-click the DEB file to open in your package manager
  2. Click Install
  3. Launch from your applications menu

First Time Setup

Log in to your account

When you first launch Bucket Buddy, you'll need to log in to your account. When you purchase Bucket Buddy you will receive an email to set your password to your Just Tom account. In this account you can manage licenses and subscriptions purchased from me.

It is these same credentials you should use to log in to Bucket Buddy.

After logging in, Bucket Buddy will greet you with an interactive onboarding tour that guides you through some of our main features. You can skip the tour and explore on your own, or follow it step-by-step for a guided experience. You can always restart the tour later from the Help menu.

Quick Start Guide

Option 1: Import from Laravel Herd

If you have Laravel Herd installed, Bucket Buddy can automatically detect and configure your Laravel projects:

  1. Click "Import Site" or press Cmd+I (Mac) / Ctrl+I (Windows/Linux)
  2. Bucket Buddy will show you a list of all your Laravel Herd projects. Select the project you want to connect
  3. Review the setup options:
    • ✅ Color: Choose a color to help you visually identify this site
    • ✅ Provider: Select the provider type setup you want the bucket to have
    • ✅ Install S3 composer package : If your project is built with PHP and uses composer, we will attempt to install the league/flysystem-aws-s3-v3 package
    • ✅ Automatically set ENV variables : if your project has an .env file we will comment out existing keys with the same names so you do not lose your original values, and place a new set of values in the .env file for your new bucket.
  4. Click "Import Site"

Option 2: Create a New Site (Manual Setup)

If you're not using Laravel Herd, or want to create a standalone S3 bucket:

  1. Click "Create Site" or press Cmd+N (Mac) / Ctrl+N (Windows/Linux)
  2. Fill in the site details:
    • Name: Enter a name for your site (e.g., "my-blog", "photo-app")
    • Provider: Select the provider type setup you want the bucket to have
    • Local Project Path (optional): If you want Bucket Buddy to attempt to update .env variables or install the s3 composer package
    • Color: Choose a color to help you visually identify this site
  3. If you selected a local project path, additional options may be available:
    • ✅ Install S3 composer package : If your project is built with PHP and uses composer, we will attempt to install the league/flysystem-aws-s3-v3 package
    • ✅ Automatically set ENV variables : if your project has an .env file we will comment our existing keys with the same names so you do not lose your original values, and place a new set of values in the .env file for your new bucket.
  4. Click "Create Site"

That's it! Your Laravel app is now connected to Bucket Buddy and ready to use S3 storage locally, immediately.

Bucket Buddy will:

  • Create a new site
  • Generate secure S3 credentials
  • Install the required S3 package in your Laravel project (if needed)
  • Update your Laravel .env file with the S3 configuration (if needed)

Using Your Site

Once your site is created, you can:

  1. Browse Files

    • Click on your site in the sidebar
    • The file browser opens showing your buckets
    • Switch between Private and Public buckets using the tabs (if provider is Cloudflare R2)

  2. Upload Files

    • Drag and drop files directly into the file browser
    • Or click the Upload button to select files

  3. Connect Your Laravel App (if not auto-configured)

    • Click the Settings icon (⚙️) for your site
    • Click "View Credentials"
    • Copy the credentials shown
    • Paste them into your Laravel project's .env file:
env
AWS_ACCESS_KEY_ID=your-access-key-here
AWS_SECRET_ACCESS_KEY=your-secret-key-here
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=your-site-name-private
AWS_ENDPOINT=http://localhost:9876
AWS_USE_PATH_STYLE_ENDPOINT=false

That's all you need! Your Laravel app can now use Bucket Buddy for S3 storage during development.

Next Steps

Need Help?

If you encounter any issues during setup, check the Troubleshooting Guide or enable Debug Mode to export detailed logs.