MinIO S3-Compatible Object Storage Deployment Guide

Key Features

Feature	Description
S3 Compatibility	Full Amazon S3 API compatibility for seamless integration
Erasure Coding	Data protection with configurable redundancy levels
Bitrot Protection	Automatic detection and healing of data corruption
Encryption	Server-side and client-side encryption support
Identity Management	LDAP, OpenID Connect, and built-in IAM policies
Replication	Site-to-site and bucket-level replication

Prerequisites

System Requirements

Component	Minimum	Recommended
CPU	2 cores	4+ cores
RAM	4 GB	8+ GB
Storage	20 GB SSD	100+ GB NVMe
Network	1 Gbps	10 Gbps
OS	Ubuntu 22.04 LTS	Ubuntu 24.04 LTS

Required Ports

Port	Service	Purpose
9000	MinIO API	S3 API endpoint
9001	MinIO Console	Web management interface

Binary Installation (Recommended)

Download and Install MinIO

Install MinIO binary

# Download MinIO binary
wget https://dl.min.io/server/minio/release/linux-amd64/minio

# Make executable and move to system path
chmod +x minio
sudo mv minio /usr/local/bin/

# Verify installation
minio --version

Create Dedicated User and Directories

Setup user and directories

# Create minio user and group
sudo groupadd -r minio-user
sudo useradd -M -r -g minio-user minio-user

# Create data directory
sudo mkdir -p /data/minio
sudo chown -R minio-user:minio-user /data/minio

# Create configuration directory
sudo mkdir -p /etc/minio
sudo chown -R minio-user:minio-user /etc/minio

Configure Environment Variables

Create the MinIO environment configuration file:

/etc/default/minio

# MinIO root credentials (change these!)
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=your-secure-password-here

# Storage volumes
MINIO_VOLUMES="/data/minio"

# Server URL (use your domain or IP)
MINIO_SERVER_URL="https://minio.example.com:9000"

# Console address
MINIO_OPTS="--console-address :9001"

# Optional: Enable browser console
MINIO_BROWSER=on

Create Systemd Service

/etc/systemd/system/minio.service

[Unit]
Description=MinIO Object Storage
Documentation=https://min.io/docs/minio/linux/index.html
Wants=network-online.target
After=network-online.target
AssertFileIsExecutable=/usr/local/bin/minio

[Service]
Type=notify
User=minio-user
Group=minio-user
EnvironmentFile=/etc/default/minio
ExecStart=/usr/local/bin/minio server $MINIO_VOLUMES $MINIO_OPTS
Restart=always
RestartSec=5
LimitNOFILE=65536
TasksMax=infinity
TimeoutStopSec=infinity
SendSIGKILL=no

[Install]
WantedBy=multi-user.target

Start MinIO Service

Enable and start MinIO

sudo systemctl daemon-reload
sudo systemctl enable minio
sudo systemctl start minio

# Check status
sudo systemctl status minio

# View logs
sudo journalctl -u minio -f

Docker Installation

Quick Docker Run

Run MinIO container

# Create data directory
mkdir -p ~/minio/data

# Run MinIO container
docker run -d \
  --name minio \
  --restart unless-stopped \
  -p 9000:9000 \
  -p 9001:9001 \
  -v ~/minio/data:/data \
  -e "MINIO_ROOT_USER=minioadmin" \
  -e "MINIO_ROOT_PASSWORD=your-secure-password-here" \
  quay.io/minio/minio server /data --console-address ":9001"

Docker Compose Configuration

docker-compose.yml

version: '3.8'

services:
  minio:
    image: quay.io/minio/minio:latest
    container_name: minio
    restart: unless-stopped
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - minio_data:/data
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: your-secure-password-here
    command: server /data --console-address ":9001"
    healthcheck:
      test: ["CMD", "mc", "ready", "local"]
      interval: 30s
      timeout: 20s
      retries: 3

volumes:
  minio_data:
    driver: local

TLS/SSL Configuration

Using Let's Encrypt with Certbot

Install and obtain certificate

# Install Certbot
sudo apt update
sudo apt install certbot -y

# Obtain certificate (standalone mode)
sudo certbot certonly --standalone -d minio.example.com

# Create MinIO certs directory
sudo mkdir -p /etc/minio/certs

# Copy certificates with correct names
sudo cp /etc/letsencrypt/live/minio.example.com/fullchain.pem \
  /etc/minio/certs/public.crt
sudo cp /etc/letsencrypt/live/minio.example.com/privkey.pem \
  /etc/minio/certs/private.key

# Set permissions
sudo chown -R minio-user:minio-user /etc/minio/certs
sudo chmod 600 /etc/minio/certs/private.key

# Restart MinIO
sudo systemctl restart minio

Certificate Auto-Renewal

Create a renewal hook at /etc/letsencrypt/renewal-hooks/deploy/minio.sh:

minio.sh

#!/bin/bash
cp /etc/letsencrypt/live/minio.example.com/fullchain.pem /etc/minio/certs/public.crt
cp /etc/letsencrypt/live/minio.example.com/privkey.pem /etc/minio/certs/private.key
chown minio-user:minio-user /etc/minio/certs/*
systemctl restart minio

Make executable

sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/minio.sh

MinIO Client (mc)

Installation

Install mc

# Download mc binary
wget https://dl.min.io/client/mc/release/linux-amd64/mc

# Make executable and move to path
chmod +x mc
sudo mv mc /usr/local/bin/

# Verify installation
mc --version

Configure MinIO Alias

Add alias

# Add your MinIO server as an alias
mc alias set myminio https://minio.example.com:9000 minioadmin your-secure-password

# Verify connection
mc admin info myminio

Common Operations

Command	Description
`mc mb myminio/bucket-name`	Create a new bucket
`mc ls myminio/`	List all buckets
`mc cp file.txt myminio/bucket/`	Upload a file
`mc cp -r dir/ myminio/bucket/`	Upload directory recursively
`mc rm myminio/bucket/file.txt`	Delete a file
`mc mirror dir/ myminio/bucket/`	Synchronize directory to bucket

User & Access Management

Creating Users

User management

# Create a new user
mc admin user add myminio newuser newuser-secret-key

# List all users
mc admin user list myminio

# Get user info
mc admin user info myminio newuser

# Disable/Enable a user
mc admin user disable myminio newuser
mc admin user enable myminio newuser

# Remove a user
mc admin user remove myminio newuser

Built-in Policies

Policy	Permissions
readonly	Read-only access to all buckets
writeonly	Write-only access to all buckets
readwrite	Full read/write access to all buckets
diagnostics	Access to diagnostic tools
consoleAdmin	Full administrative access

Assign Policy to User

Attach policy

# Attach built-in policy
mc admin policy attach myminio readwrite --user newuser

# View user policies
mc admin user info myminio newuser

Custom Bucket Policy

Create custom policy

# 1. Create policy file
cat > /tmp/bucket-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::mybucket",
        "arn:aws:s3:::mybucket/*"
      ]
    }
  ]
}
EOF

# 2. Add custom policy
mc admin policy create myminio mybucket-policy /tmp/bucket-policy.json

# 3. Attach to user
mc admin policy attach myminio mybucket-policy --user newuser

Distributed Deployment

Distributed MinIO requires a minimum of 4 drives. The system uses erasure coding to protect data.

Configuration	Drives Lost	Data Status
4 drives	Up to 2	Readable and writable
8 drives	Up to 4	Readable and writable
16 drives	Up to 8	Readable and writable

Multi-Node Setup (4 Nodes)

/etc/default/minio (all nodes)

MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=your-secure-password-here

# All nodes must use the same server pool definition
MINIO_VOLUMES="https://minio{1...4}.example.com:9000/data/minio"

MINIO_OPTS="--console-address :9001"

Single-Node Multi-Drive Setup

/etc/default/minio

MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=your-secure-password-here

# Multiple drives on single node
MINIO_VOLUMES="/data/disk{1...4}"

MINIO_OPTS="--console-address :9001"

Backup & Recovery

Bucket Versioning

Enable versioning

# Enable versioning on a bucket
mc version enable myminio/mybucket

# Check versioning status
mc version info myminio/mybucket

# List object versions
mc ls --versions myminio/mybucket/

Cross-Bucket Replication

Setup replication

# Enable versioning on both buckets (required)
mc version enable myminio/source-bucket
mc version enable myminio/dest-bucket

# Add replication rule
mc replicate add myminio/source-bucket \
  --remote-bucket "https://accesskey:secretkey@remote-minio:9000/dest-bucket" \
  --replicate "delete,delete-marker,existing-objects"

Backup with mc mirror

Mirror backups

# Mirror bucket to local directory
mc mirror myminio/mybucket /backup/minio/mybucket

# Mirror to another MinIO instance
mc mirror myminio/mybucket backup-minio/mybucket

# Schedule with cron
0 2 * * * /usr/local/bin/mc mirror --overwrite myminio/mybucket /backup/minio/mybucket

Monitoring & Observability

Prometheus Metrics

Generate Prometheus config

# Generate Prometheus scrape configuration
mc admin prometheus generate myminio

prometheus.yml

scrape_configs:
  - job_name: minio
    metrics_path: /minio/v2/metrics/cluster
    scheme: https
    static_configs:
      - targets: ['minio.example.com:9000']
    bearer_token: <generated-token>

Health Check Endpoints

Endpoint	Purpose
/minio/health/live	Liveness probe for load balancers
/minio/health/ready	Readiness probe for Kubernetes
/minio/health/cluster	Cluster health with detailed status

Server Status Commands

Status commands

# Server information
mc admin info myminio

# Real-time server logs
mc admin logs myminio

# Trace API calls
mc admin trace myminio

# Check service status
mc admin service status myminio

Troubleshooting

Issue	Solution
Connection refused	Check firewall rules and verify MinIO is running
Access denied	Verify credentials and check IAM policies
Certificate errors	Ensure certificates are in /etc/minio/certs with correct names
Slow performance	Check disk I/O, network bandwidth, and erasure coding overhead
Out of space	Enable lifecycle policies or expand storage capacity

Debug Logging

Enable debug logging

# Enable debug logging
export MINIO_DEBUG=on
sudo systemctl restart minio

# View detailed logs
sudo journalctl -u minio -f --output=verbose

# API call tracing
mc admin trace -v myminio

Disk Health Check

Check disk health

# Check disk status in distributed mode
mc admin info myminio --json | jq '.info.backend'

# Heal damaged objects
mc admin heal myminio

# Recursive heal with status
mc admin heal -r myminio/mybucket

MinIO Object Storage Guide