How to Deploy MinIO: Single Binary, Docker, Docker Compose & Kubernetes

MinIO is an S3-compatible object storage server that is used for storing unstructured data like backups, documents, images, videos, application files, and more. MinIO supports an Amazon S3-compatible API, which makes it easy to use in modern applications and platforms.

MinIO is used for many different purposes - including storing backups, documents, media, and cloud-native applications. MinIO is perfect for self-hosting scenarios when organizations want scalable and cost-efficient object storage that does not depend on any cloud provider.

Unlike other storage solutions, MinIO is lightweight, easy to deploy, fully scalable, and compatible with the whole Amazon S3 ecosystem. You can easily use MinIO for your small development environment or big Kubernetes clusters and configure it depending on your needs.

Each way of deploying MinIO will be used in different scenarios. Using MinIO as a single binary will be helpful for local testing purposes, using Docker and Docker Compose will be handy when you need to containerize your storage solution, and using Kubernetes will give you a scalable and production-ready solution.

In this blog, we are going to discuss four popular ways of deploying MinIO and where each way should be used:

• Single Binary
• Docker
• Docker Compose
• Kubernetes

Method 1: Running MinIO as a Plain Binary

This is the easiest way to set up MinIO and serves as an appropriate starting point if you have not used MinIO before. It involves nothing more than downloading the server executable and running it without installing any containers or orchestrating tools.

It should be noted, however, that the MinIO server will be running only when the process is active. Once the process is interrupted, the server will stop operating.

Let's begin by downloading the MinIO server binary:

wget https://dl.min.io/server/minio/release/linux-amd64/minio

Afterwards, let us make it executable and put it somewhere in our PATH so we can use it everywhere:

chmod +x minio 
sudo mv minio /usr/local/bin/

You can verify that minio was installed successfully by running the following command:

minio --version

To operate properly, MinIO needs some place on a disk to keep its objects and metadata. Let us create the storage folder:

mkdir -p ~/minio-data

Next, start the server by referencing this directory. The values for MINIO_ROOT_USER and MINIO_ROOT_PASSWORD become your login to the web dashboard; therefore, you should define your own values below instead of repeating the example:

MINIO_ROOT_USER="<your-username>" \
MINIO_ROOT_PASSWORD="<your-secure-password>" \
minio server ~/minio-data --console-address ":9001"

Replace <your-username> and <your-secure-password> with the credentials you want to use for the MinIO Console.

After startup, MinIO will output where it listens for incoming connections:

• API: http://127.0.0.1:9000
• WebUI: http://127.0.0.1:9001

MinIO utilizes port 9000 to provide an S3-compatible API for applications and tools to communicate with the object storage. Port 9001 runs the MinIO Console, which allows users to work with buckets, users, access policies, and stored objects via the web interface.

Keep the terminal window open and navigate your browser to http://localhost:9001. Then, log in using your credentials that you have defined above. After logging in, you will be able to access the MinIO Console, where you will be able to work with buckets, users, and objects.

Additional note: To make MinIO run even after shutting down the terminal or restarting the operating system, you can set up MinIO as a systemd service. This way, MinIO will start automatically when the system boots, and it's highly recommended for standalone usage of the object storage.

Method 2: Running MinIO in Docker

After the initial tests, the second natural step after setting up the environment will be starting the MinIO service using Docker. The container will keep running in the background independently of your terminal session, will be restarted automatically in case of a crash, and can be destroyed and re-created easily without any residual files.

If you don’t have Docker installed, install using this command:

sudo apt update
sudo apt install -y docker.io
sudo systemctl start docker
sudo systemctl enable docker

By default, all Docker commands require sudo privilege. Make yourself a member of the Docker group in order not to use sudo anymore:

sudo usermod -aG docker $USER
newgrp docker

Start the MinIO container. Several details worth mentioning about the below command: -p maps container ports to your machine, -v attaches the local directory for persistency, and --restart=always will cause Docker to automatically restart the container in case it crashed

 docker run -d --name minio --restart=always \
    -p 9000:9000 -p 9001:9001 \
    -v ~/minio-data:/data \
    -e "MINIO_ROOT_USER=<your-username>" \
    -e "MINIO_ROOT_PASSWORD=<your-secure-password>" \
    minio/minio server /data --console-address ":9001"

Replace <your-username> and <your-secure-password> with the credentials you want to use for the MinIO Console.

Check that it's actually running:

docker ps

You should see the minio container listed as Up, with both ports mapped. You can also check its startup logs to confirm there were no errors:

docker logs minio

A clean log ends with lines like this, confirming the server initialized correctly:

• API: http://172.17.0.2:9000
• WebUI: http://172.17.0.2:9001

Visit http://localhost:9001 in your browser and log in - the dashboard should load exactly as it did with the binary method, just now running as a managed container.

Common issue: If Docker refuses to start the container with an error like "address already in use" on port 9000, something else already has that port open - most often a MinIO binary process left running from Method 1. You can find and stop it with:

sudo lsof -i :9000
sudo kill -9 <PID shown above>

Then, remove the failed container and re-run the docker run command:

docker rm -f minio

Verify the container is removed:

docker ps -a | grep minio

Method 3: Running MinIO with Docker Compose

Although Docker Compose won't change the actual service being run, it will allow you to define the entire configuration in one file, instead of using a single long Docker run command. And this file is documentation in itself - anyone on your team would be able to understand it, modify it, and spin the same environment up with a single command.

If you don’t have Docker installed, install using this command:

sudo apt update
sudo apt install -y docker.io
sudo systemctl start docker
sudo systemctl enable docker

Create a directory for your Compose project:

mkdir -p ~/minio-compose
touch ~/minio-compose/docker-compose.yml
cd ~/minio-compose

In that directory, create a file docker-compose.yml that will define your service. This configuration is actually the same as the Docker run command from Method 2, only presented in a different way:

Open the docker-compose.yml file using a text editor:

nano docker-compose.yml

Then, add the following configuration to the file:

services:
  minio:
    image: minio/minio
    container_name: minio
    restart: always
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      MINIO_ROOT_USER: "<your-username>"
      MINIO_ROOT_PASSWORD: "<your-secure-password>"
    volumes:
      - ~/minio-data:/data
    command: server /data --console-address ":9001

Replace <your-username> and <your-secure-password> with the credentials you want to use for the MinIO Console.

Check whether the Docker Compose plugin is available to the system:

docker compose version

If it responds with "unknown command", that means the plugin isn't installed yet. It is not always present in Docker installations on Ubuntu, so you'll need to download it manually:

mkdir -p ~/.docker/cli-plugins
wget https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64 \
-O ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose

Now, start the stack:

docker compose up -d

Verify it's running:

docker compose ps

Visit http://localhost:9001 and log in using the credentials in your compose file. Moving forward, to start/stop this setup is easy - all you need is docker compose up -d or docker compose down.

Troubleshooting: If you encounter permission errors when deleting the MinIO data directory, the files may have been created by the MinIO container with a different user ID. In that case, remove the directory with administrative privileges:

sudo rm -rf ~/minio-data

Use this command only when you are certain that you no longer need the data stored in the directory, as it permanently deletes the MinIO data.

Note: If you encounter a permission error while downloading the Docker Compose plugin to ~/.docker/cli-plugins, make sure the directory is writable by your current user. You can use wget as an alternative to curl.

Method 4: Running MinIO on Kubernetes

This is the way you are going to implement once you start thinking about the implementation aspect of the topic, especially when thinking about the implementation of the multi-tenant SaaS platform that is supposed to self-heal, to have the ability to have controlled storage, and to be scalable. For this implementation, we are going to use MicroK8s, which is a lightweight Kubernetes cluster that runs on your computer, and we will discuss the implementation process in terms of simple YAML files.

Requirements

MicroK8s installed (installation of MicroK8s is described in steps below)

Some basic understanding of three Kubernetes objects: PersistentVolumeClaim (storage), Deployment (MinIO pod), and Service (how to access MinIO)

Step-by-Step Guide

To start, let's install MicroK8s and add our user to its group to run the following commands without having to use sudo:

sudo snap install microk8s --classic
sudo usermod -aG microk8s $USER
mkdir -p ~/.kube
sudo chown -f -R $USER ~/.kube

Let the cluster become available:

microk8s status --wait-ready

In order not to write “microk8s” before each kubectl command in this whole tutorial, let's make an alias:

alias kubectl='microk8s kubectl'

Before a PersistentVolumeClaim can successfully bind to any disk space, Kubernetes requires a storage backend. Therefore, we need to use the hostpath storage add-on, which is included in microk8s (although not recommended for production storage, but fine for our local single-node environment):

microk8s enable hostpath-storage

Let us define a namespace to group MinIO's resources apart from everything else on our cluster:

kubectl create namespace minio

Defining the Storage

Create a file named minio-pvc.yaml to define the persistent storage that MinIO will use.

nano minio-pvc.yaml

Add the following configuration to the file:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
   name: minio-pvc
   namespace: minio
spec:
   accessModes:
      - ReadWriteOnce
   resources:
      requests: 
         storage: 5Gi

Press Ctrl + S to save and Ctrl + X to exit.

It will ask Kubernetes to allocate 5Gi of persistent storage, which the MinIO pod can claim:

Defining the Workload

Create a file named minio-deployment.yaml to define the MinIO workload.

nano minio-deployment.yaml

Add the following configuration to the file:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: minio
  namespace: minio
spec:
  replicas: 1
  selector:
    matchLabels:
      app: minio
  template:
    metadata:
      labels:
        app: minio
    spec:
      containers:
        - name: minio
          image: minio/minio
          args:
            - server
            - /data
            - --console-address
            - ":9001"
          env:
            - name: MINIO_ROOT_USER
              value: "<your-username>"
            - name: MINIO_ROOT_PASSWORD
              value: "<your-secure-password>"
          ports:
            - containerPort: 9000
            - containerPort: 9001
          volumeMounts:
            - name: minio-storage
              mountPath: /data
      volumes:
        - name: minio-storage
          persistentVolumeClaim:
            claimName: minio-pvc

Replace <your-username> and <your-secure-password> with the credentials you want to use for the MinIO Console.

Press Ctrl + S to save and Ctrl + X to exit.

This will ask Kubernetes to run a single MinIO container with allocated storage and credentials specified above.

Expose it

Create a file named minio-service.yaml:

nano minio-service.yaml

Add the following configuration:

apiVersion: v1
kind: Service
metadata:
  name: minio-service
  namespace: minio
spec:
  type: NodePort
  selector:
    app: minio
  ports:
    - name: api
      port: 9000
      targetPort: 9000
      nodePort: 30900
    - name: console
      port: 9001
      targetPort: 9001
      nodePort: 30901

Press Ctrl + S to save and Ctrl + X to exit.

The NodePort service creates an exposed port on the cluster node to be able to connect to MinIO from the browser, outside the cluster:

Apply the created YAML files:

kubectl apply -f minio-pvc.yaml
kubectl apply -f minio-deployment.yaml
kubectl apply -f minio-service.yaml

Wait a second, then check everything is fine:

kubectl get pvc -n minio
kubectl get pods -n minio
kubectl get svc -n minio

The expected output is the PVC status to be "Bound" and the pod status to be "Running". Both of them will normally start with "Pending" because there is a time needed for provisioning storage and pulling the image.

Confirm the MinIO server actually started cleanly by checking the pod's logs - first grab the pod name, then view its logs:

kubectl get pods -n minio 
kubectl logs -n minio <pod-name-from-above> 

A healthy startup ends with the same kind of output you saw with the binary and Docker methods:

• API: http://10.1.x.x:9000
• WebUI: http://10.1.x.x:9001

If the pod stays stuck in Pending for more than a minute, or shows CrashLoopBackOff or ImagePullBackOff instead of Running, get more detail on what's blocking it:

kubectl describe pod -n minio <pod-name-from-above>

This will show you the actual scheduling or image-pull error at the bottom of the output under "Events" - most often it's the PVC not binding (check that the hostpath-storage addon is enabled) or the image still being pulled the first time.

Since NodePort services expose the ports of the cluster node and not the ports of the containers, open the dashboard at http://localhost:30901 (not 9001) and log in using the credentials from the Deployment file.

There are various ways to deploy MinIO, with each deployment having its unique advantages. Single Binary installation is the simplest method of setting up MinIO. On the other hand, the use of Docker involves packaging MinIO in a container, while the use of Docker Compose includes maintaining all service information in YAML files. For more sophisticated cases, Kubernetes makes use of the containerized method, but with the addition of persistence, deployments, and services.

Having understood the above four ways of deploying MinIO, the aim should be to select the deployment process that suits your project, from the simplest form of experimentation to Kubernetes deployments. It is not a case of picking the most complicated deployment process, but the one that fits well.

To read more about How to Set Up Multiple Odoo Instances in a Single Docker Compose YAML, refer to our blog How to Set Up Multiple Odoo Instances in a Single Docker Compose YAML.