Local S3 development using MinIO

When building medium to large Laravel application we will often use Amazon S3 (or a similar service) to store our files.

During local development it's tempting to fall back on the local storage disk during development. It’s fast, it’s easy, and Laravel makes it dead simple to switch. But this also introduces a big gap between dev and production—especially if your code depends on S3-specific behavior or configuration.

That’s exactly the situation I found myself in. I wanted a local environment that behaved more like production without actually connecting to S3 . The solution I ended up with? MinIO: a lightweight, S3-compatible object storage server you can run locally.

In this post I’ll guide you through the steps to get started with MinIO and Laravel.

Setting up MinIO

There are several ways to install and run MinIO—Docker, downloading the binary directly, or using a package manager. Personally, I went with ~Homebrew~.

To install MinIO via Homebrew, you can run this command:

brew install minio/stable/minio

Once installed you should be able to start your MinIO server:

minio server start

Once the server has started you should see the address your server is running on, as well as the credentials to log in.

There are two addresses:

• API: this is the address you will use to connect Laravel to MinIO
• WebUI: this is the address of the web ui that will allow you to manage your server.

Configuring the server

First you will want to configure your server, you will want to do 2 things to get started:

1. Create a bucket
2. Create an access key
3. Update the configuration in your Laravel app

Creating a bucket

You can create a bucket by going to “Buckets”, which you can find in the left navigation menu under the “Administrator” section.

In the “Buckets” screen you will find a “Create Bucket” button on the top right. For this tutorial you can just create a bucket by specifying the name and hitting the create button.

In a default Laravel installation you can now configure the bucket by setting the AWS_BUCKET env variable to the name of the bucket you just created.

Creating an access key

The access key and secret will allow Laravel to interract with the MinIO server.

You can create an access key by navigating to the “Access Keys” page in the MinIO admin panel. For this tutorial you can keep all default values, but make sure to copy the “Access Key” and “Secret Key” to your .env file:

AWS_ACCESS_KEY_ID=your access key
AWS_SECRET_ACCESS_KEY=your secret key

Setting up Laravel

Besides the bucket and access keys there are some more things you will want to add to your configuration.

The AWS_ENDPOINT variable should be set to the API address you see after starting the MinIO server.

AWS_DEFAULT_REGION this can be set to wather region is configured in MinIO. You can check this by going to Configuration > Region in the MinIO admin panel.

Now you should be ready to switch the file system of your app by setting FILESYSTEM_DISK to s3.

Testing the integration

Now we are all setup we can test if everything works like we wanted. The easiest way is to run some simple code with tinker (php artisan tinker):

Storage::disk('s3')->put('test.txt', 'Hello from Laravel + MinIO!');

After executing the code above you should be able to go to the admin UI of Minio, navigate to the bucket you created an see the file test.txt.

Hooray! 🎉