Laravel Sail Integration with RustFS

RustFS is a high-performance, S3-compatible object storage system built for modern cloud-native and AI workloads. Laravel, one of the world’s most popular PHP frameworks, supports RustFS natively via Laravel Sail and the Flysystem S3 adapter.

This guide provides a complete, end-to-end integration walkthrough for Laravel + Laravel Sail + RustFS on Ubuntu 24.04.

Laravel Sail added first-class support for RustFS Reference: https://github.com/laravel/sail/pull/822

Architecture Overview

Laravel Sail runs the Laravel application inside Docker containers
RustFS provides S3-compatible object storage
Flysystem S3 Adapter bridges Laravel and RustFS
Communication uses standard AWS S3 APIs

Prerequisites

Ubuntu 24.04 LTS
sudo privileges
Internet access

1. Install PHP 8.3

1.1 Update System and Install Dependencies

sudo apt update
sudo apt install -y lsb-release ca-certificates apt-transport-https software-properties-common

1.2 Add PHP Repository (Ondřej Surý PPA)

sudo add-apt-repository ppa:ondrej/php
sudo apt update

1.3 Install PHP 8.3 and Required Extensions

sudo apt install -y php8.3   php8.3-cli php8.3-fpm php8.3-mysql php8.3-curl   php8.3-mbstring php8.3-xml php8.3-zip   php8.3-bcmath php8.3-gd

1.4 Verify Installation

php -v

2. Install Docker Engine

Docker is required for both Laravel Sail and RustFS.

2.1 Remove Conflicting Packages

sudo apt-get remove -y docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc

2.2 Install Docker Repository and GPG Key

sudo apt-get update
sudo apt-get install -y ca-certificates curl

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg   -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

2.3 Add Docker Repository

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

2.4 Install Docker Engine

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

2.5 Verify Docker Installation

sudo docker run hello-world

3. Install RustFS (Docker Deployment)

RustFS is deployed as a single-node Docker service for development and testing.

mkdir -p data logs
sudo chown -R 10001:10001 data logs

docker run -d   --name rustfs   -p 9000:9000   -p 9001:9001   -v $(pwd)/data:/data   -v $(pwd)/logs:/logs   rustfs/rustfs:latest

S3 API Endpoint: http://localhost:9000
Management Console: http://localhost:9001
Default Credentials: rustfsadmin / rustfsadmin (unless overridden)

Create a bucket named test-bucket using the RustFS console.

4. Install Composer

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"
sudo mv composer.phar /usr/local/bin/composer

composer -V

5. Create Laravel Project with Sail

5.1 Create Laravel Project

composer create-project laravel/laravel rustfs-laravel
cd rustfs-laravel

5.2 Install Laravel Sail

php artisan sail:install

5.3 Start Sail Environment

./vendor/bin/sail up -d

6. Install Flysystem S3 Adapter

Laravel requires the AWS S3 Flysystem adapter to communicate with RustFS.

./vendor/bin/sail composer require league/flysystem-aws-s3-v3

7. Configure Laravel to Use RustFS

Edit the .env file in the project root:

FILESYSTEM_DISK=s3

AWS_ACCESS_KEY_ID=rustfsadmin
AWS_SECRET_ACCESS_KEY=rustfsadmin
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=test-bucket

# RustFS S3 API endpoint (Docker bridge on Linux)
AWS_ENDPOINT=http://172.17.0.1:9000

# Required for S3-compatible storage
AWS_USE_PATH_STYLE_ENDPOINT=true

8. Validation Integration (Smoke Test)

This step verifies end-to-end compatibility between Laravel Sail and RustFS, including write, read, existence check, and latency measurement.

Edit routes/web.php and add:

use Illuminate\Support\Facades\Route;
use Illuminate\Support\Facades\Storage;

Route::get('/test-rustfs', function () {
    $fileName = 'rustfs-smoke-test-' . time() . '.txt';
    $content = 'Hello RustFS! This is a Laravel Sail integration test.';

    try {
        // Write object
        $start = microtime(true);
        Storage::disk('s3')->put($fileName, $content);
        $writeLatency = round((microtime(true) - $start) * 1000, 2);

        // Existence check
        $exists = Storage::disk('s3')->exists($fileName);

        // Read object
        $readContent = Storage::disk('s3')->get($fileName);

        return response()->json([
            'status' => 'success',
            'file' => $fileName,
            'exists' => $exists,
            'write_latency_ms' => $writeLatency,
            'content_read' => $readContent,
            'driver_config' => config('filesystems.disks.s3'),
        ]);
    } catch (\Throwable $e) {
        return response()->json([
            'status' => 'error',
            'message' => $e->getMessage(),
        ], 500);
    }
});

Open your browser and visit:

http://localhost/test-rustfs

Expected Result

A successful response confirms:

Successful S3 authentication
Object PUT operation
Object existence check (HEAD)
Object GET operation

{
  "status": "success"
}

Conclusion

Laravel Sail integrates seamlessly with RustFS using standard S3 APIs. This setup allows PHP developers to adopt RustFS as a high-performance, self-hosted object storage backend with minimal configuration.

For advanced topics such as clustering, TLS, presigned URLs, and production hardening, refer to the official RustFS documentation.