MinIO: object storage with an S3-compatible API

MinIO runs as a server process that offers the S3 API. Any client that can talk to S3 — the AWS CLI, `mc`, or an SDK in Python, Go, or Java — can talk to MinIO. That's the whole point: you don't build vendor lock-in, because the API is standardized.

The price you pay is management. AWS S3 handles redundancy, monitoring, and credential rotation for you. With MinIO, you're responsible for that yourself. Self-hosting sounds great, until something falls over on Sunday night at half past eleven. Then you're not a customer waiting on the helpdesk. Then you *are* the helpdesk.

Installing and starting the server

1. Download the MinIO server

Get the binary from the official site. The download URL contains the version number, so check for a newer version with each new release.

wget https://dl.min.io/server/minio/release/linux-amd64/minio
chmod +x minio
sudo mv minio /usr/local/bin/

The binary is self-contained — no dependencies, no packages. That makes it easy to install, but you need to handle a service manager yourself to keep the process running.

2. Set the root credentials

MinIO needs a root user. Set those as environment variables, not in a config file. The server reads them at startup.

export MINIO_ROOT_USER=minioadmin
export MINIO_ROOT_PASSWORD=a-long-and-random-password

Choose a password of at least 8 characters. In production, use something with 32 characters from a password manager. This is the key to all your data.

3. Start the server

minio server /data --address ":9000" --console-address ":9001"

The `/data` directory is where MinIO stores the objects. Make sure it's on a disk with enough space. The `--address` and `--console-address` flags determine where the API and web console listen.

If you run this command in a terminal, the server stops when you close the terminal. For a real deployment, use systemd or a container platform. MinIO has an official systemd unit in the repository.

4. Create a bucket

A bucket is the highest container in object storage — comparable to a disk partition. Without a bucket, you can't store anything.

mc alias set local http://localhost:9000 minioadmin 'a-long-and-random-password'
mc mb local/testbucket

The first command registers your MinIO server as `local` in the client. The second creates a bucket. You can also do this via the web console at `http://localhost:9001`.

Using the client

The MinIO Client (`mc`) is a command-line tool that works with any S3-compatible server. You can use it not only to manage MinIO, but also AWS S3, Google Cloud Storage, and other S3 implementations.

wget https://dl.min.io/client/mc/release/linux-amd64/mc
chmod +x mc
sudo mv mc /usr/local/bin/

With `mc ls local` you see the buckets. With `mc cp bestand.txt local/testbucket/` you upload a file. With `mc ls --recursive local/testbucket` you see everything in the bucket, including objects in pseudo-folders.

The advantage of `mc` over the AWS CLI is that you can have multiple servers in one configuration. You switch with `mc ls` between your local MinIO and AWS S3 without resetting credentials each time. That also makes it a handy tool for migrating data between providers.

Clustering

One server is not production. MinIO supports distributed mode, where multiple nodes together form one storage system. The data is then replicated across the nodes, so you can lose nodes without data loss.

minio server http://node1.local/data http://node2.local/data \
  http://node3.local/data http://node4.local/data

This starts a cluster of four nodes. MinIO uses erasure coding: it splits objects into fragments and distributes them across the nodes. With four nodes, you can lose two and everything remains readable. The math is simple: with more nodes, you can absorb more loss, but each node costs maintenance and power.

Setting up a cluster is not something you do in an afternoon. You need identical hardware, a good network, and monitoring. For a first introduction, a single server is enough.

Docker Buildx cache

A practical application: MinIO can serve as a cache backend for Docker Buildx. Storing build cache on S3-compatible storage means your CI/CD pipeline can reuse the cache, even if the runner itself is not persistent.

docker buildx create --driver docker-container \
  --config buildkitd.toml

In `buildkitd.toml` you point to your MinIO server as an S3 endpoint. Docker supports this since Buildx 0.8. It works, but you do need to configure the cache with the correct credentials and the correct bucket path. The Buildx documentation is clear on this.

Common problems

The server starts but the web console is not reachable. Check whether you have set `--console-address`. Without that flag, MinIO picks a random port and logs it in the output. If you have a firewall, open both 9000 and 9001.

`mc` gives an access denied error. Your credentials are wrong, or you have not exported them properly. Check whether `MINIO_ROOT_USER` and `MINIO_ROOT_PASSWORD` are set correctly in the shell where the server runs. The server only reads them at startup.

The disk is full but MinIO keeps writing. MinIO does not stop writing automatically. You need to set up monitoring on disk usage yourself. A full disk leads to corrupt objects. This is one of the things a managed service solves for you.

Verification

Upload a test file and retrieve it again:

echo "test" > test.txt
mc cp test.txt local/testbucket/
mc cat local/testbucket/test.txt

If you see `test` back, the whole chain works: server, client, bucket, and storage. For a production environment, you also test restarting the server and check whether the data is still there after a reboot.

MinIO is a good alternative to AWS S3 if you want to keep your data local or avoid egress costs. It is not a replacement for a backup system — that you are still responsible for yourself.