What is MinIO (Object Storage)

Do Not Save All Files on the Server

1. Server Full: Your disk space is running out. The application crashes because it cannot write logs.
2. Scaling Becomes a Nightmare: Due to high traffic, you add one more server (Server B) behind the Load Balancer. However, if user A upload's profile photo and request log in to Server A, the photo will be saved on Server A. When user A refresh the page and happens to be redirected to Server B, the photo is gone! The files are out of sync.
3. Docker Ephemeral: You start using Docker. You redeploy the container, and boom! All user upload files are lost due to the ephemeral (temporary) nature of containers.
4. Hard Backup: Every time you want to backup source code, you have to filter the uploads whose size is hundreds of Gigabytes. Application files and user files are mixed up.

What is Object Storage?

1. Key: The unique name of the identifier (example: 2026/08/baju.jpg).
2. Data: The contents of the file itself (binary).
3. Metadata: Additional information about the file (example: uploaded by whom, what size, what format).

Bucket: app-uploads
 ├── object-1 (Key: user-1-profile.jpg)
 ├── object-2 (Key: invoice-001.pdf)
 └── object-3 (Key: backup.zip)

What is MinIO?

• Self-hosted: You can install MinIO on your own VPS. You don't have to pay a fortune to cloud provider if budget is still limited.
• S3-Compatible: (This is the most important thing, I discuss it specifically in the next point).
• Very Light & Fast: Written in Go, runs on Docker very smoothly.
• Great for Kubernetes: MinIO is a first-class citizen in the Cloud-Native ecosystem.

Understanding the "S3-Compatible" Concept

 Application (Using S3 SDK)
           |
           | Speaking "S3 Language"
           v
       ┌───────────┐
       | S3 APIs |
       └─┬───────┬─┘
         |       |
    Can go to or to
         v v
      MinIO Amazon S3

Important MinIO Components

• Server: The machine or container on which MinIO runs.
• Client: Your application (Backend API) that request to save/retrieve files.
• Bucket: Primary container. Typically one application is split per bucket (e.g. bucket-staging, bucket-prod).
• Object: The file you saved (photo, pdf).
• Object Key: Unique string to identify the object.
• Metadata: Data about data (example: Content-Type: image/jpeg).
• Access Key & Secret Key: Username and Password for the API. Never leak!
• Endpoint: URL where the MinIO server can be accessed (eg: http://localhost:9000).
• Policy: Rules about who can read/write to a particular bucket.

users/
  123/
    profile.jpg

MinIO vs Local Filesystem

Application Architecture with MinIO

User
  |
  v
Frontend (Web/Mobile)
  |
  v
Backend API (Laravel/Go/Node.js)
  |
  +------------------> PostgreSQL (Saving Metadata/References)
  |
  +------------------> MinIO (Save the Physical File)

• id: 123
• name: Budi
• avatar_path: avatars/users/123/profile-xyz.jpg (This is the Object Key!)

File Upload: What Actually Happens?

1. Frontend sends image to Backend API.
2. Backend API validate (size is OK? Is the format really an image?).
3. Backend generates a unique Object Key (eg using UUID).
4. Backend sends files to MinIO using S3 Client.
5. MinIO responds "OK".
6. The backend saves the Object Key to the Database (PostgreSQL).
7. Backend replies to Frontend "Upload Successful".

Download and Access File

1. Bucket Public: Files can be accessed by anyone via the MinIO URL. Suitable for web assets (logo, banner).
2. Backend as Proxy: Frontend request to Backend, Backend pulls from MinIO, then Backend gives it to Frontend. (Safe, but burdens Backend server RAM/Bandwidth).
3. Presigned URL (Most Recommended):

User request file -> Access rights verification backend -> 
Backend generate Presigned URL (without file download) -> 
Users download directly from MinIO using this URL.

Integrasi MinIO dengan Laravel

FILESYSTEM_DISK=s3

AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=minioadmin
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=app-storage
AWS_ENDPOINT=http://localhost:9000
AWS_USE_PATH_STYLE_ENDPOINT=true

use Illuminate\Support\Facades\Storage;
use Illuminate\Support\Str;

// Generate nama unik
$fileName = Str::uuid() . '.' . $request->file('avatar')->getClientOriginalExtension();
$objectKey = 'users/' . $userId . '/' . $fileName;

// Upload ke MinIO (S3 Disk)
Storage::disk('s3')->put(
    $objectKey,
    file_get_contents($request->file('avatar'))
);

// Simpan $objectKey ke Database...

Integrasi MinIO dengan Golang

package main

import (
	"context"
	"log"
	"github.com/minio/minio-go/v7"
	"github.com/minio/minio-go/v7/pkg/credentials"
)

func main() {
	endpoint := "localhost:9000"
	accessKeyID := "minioadmin"
	secretAccessKey := "minioadmin"

	// Init S3 Client
	minioClient, err := minio.New(endpoint, &minio.Options{
		Creds:  credentials.NewStaticV4(accessKeyID, secretAccessKey, ""),
		Secure: false, // true untuk HTTPS (production)
	})
	if err != nil {
		log.Fatalln(err)
	}

	// Upload Object
	bucketName := "app-storage"
	objectName := "documents/report-xyz.pdf"
	filePath := "/tmp/report-xyz.pdf"

	info, err := minioClient.FPutObject(context.Background(), bucketName, objectName, filePath, minio.PutObjectOptions{ContentType: "application/pdf"})
	if err != nil {
		log.Fatalln(err)
	}

	log.Printf("Successfully uploaded %s of size %d\n", objectName, info.Size)
}

MinIO dengan Docker

version: '3.8'
services:
  minio:
    image: minio/minio
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    ports:
      - "9000:9000"  # API Port
      - "9001:9001"  # Console/Web UI Port
    volumes:
      - minio_data:/data # INI SANGAT PENTING!

volumes:
  minio_data:

• port 9000: Ini port API. Aplikasimu (Laravel/Go) nembak ke sini.
• port 9001: Ini Web UI/Console. Kamu bisa buka di browser untuk lihat-lihat bucket secara visual.
• volumes: minio_data:/data: Tanpa ini, setiap kali container MinIO mati atau di-restart, semua file upload kamu HILANG. Persistent volume memastikan file tetap ada secara fisik di host machine.

MinIO dalam Production

• HTTPS: API S3 wajib pakai SSL/TLS.
• Access Management: Jangan pakai akun root (MINIO_ROOT_USER) di aplikasi. Buat User khusus di MinIO yang policy-nya hanya bisa Read/Write ke bucket tertentu (Least Privilege).
• Persistent Disk: Gunakan block storage yang reliabel, dengan konfigurasi RAID atau ter-backup berkala.
• High Availability: Di production skala besar, MinIO di-deploy dalam mode Distributed (minimal 4 node) agar kalau 1 server mati, file tetap aman (Disaster Recovery).

MinIO + Nginx

Internet
   | (HTTPS)
   v
Nginx (Termination SSL)
   |
   +----> api.example.com (Ke Backend Laravel/Go)
   |
   +----> storage.example.com (Ke MinIO port 9000)
   |
   +----> console.storage.example.com (Ke MinIO UI port 9001)

Security (Keamanan)

• Jangan Expose Secret Key: Secret Key ibarat password database. Jangan taruh di Frontend (React/Vue/Mobile App). Komunikasi ke MinIO harus selalu lewat Backend-mu, atau lewat Presigned URL yang di-generate Backend.
• Jangan Hardcode Credential: Selalu gunakan Environment Variable (.env).
• Batasi Bucket Policy: Jangan buat semua bucket "Public". Bucket KTP/Invoice harus "Private".
• Validasi File di Backend: Jangan percaya request upload user. Cek MIME type-nya, batasi ukurannya (misal maksimal 5MB). File berbahaya (seperti .php atau .exe palsu) bisa merusak sistem jika tidak difilter.

Kesalahan yang Sering Dilakukan Junior Developer

1. Menyimpan binary file besar langsung di PostgreSQL: (BLOB). Kenapa salah? DB jadi super berat, backup jadi lama, memory habis. Solusi: Simpan file di MinIO, simpan URL/Key di DB.
2. Menggunakan nama file asli sebagai Object Key: profile_pic.jpg. Dampaknya: File ketimpa sama user lain. Solusi: Pakai UUID.
3. Membuat bucket KTP menjadi public: Dampaknya: Data bocor, aplikasi masuk berita (kasus kebocoran data). Solusi: Bucket private + Presigned URL.
4. Menaruh Access Key MinIO Production di Git/Github: Dampaknya: Hacker bot akan scan repo-mu, masuk ke MinIO kamu, hapus semua datamu, dan minta tebusan ransomware. Solusi: Selalu ignore .env.
5. Tidak memikirkan ukuran file: User upload video 1 GB langsung ke RAM backend sebelum di-forward ke MinIO. Dampaknya: Server langsung Out of Memory. Solusi: Kasih batasan upload size di API, atau gunakan Presigned Upload URL agar user langsung upload ke MinIO.

Database Schema untuk File Storage

CREATE TABLE files (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    original_name VARCHAR(255) NOT NULL,
    object_key TEXT NOT NULL,
    bucket VARCHAR(100) NOT NULL,
    mime_type VARCHAR(100),
    size_bytes BIGINT,
    uploaded_by UUID REFERENCES users(id),
    created_at TIMESTAMP DEFAULT NOW()
);

Studi Kasus: Mini Bank Application

                    ┌──────────────┐
                    │  React App   │
                    └──────┬───────┘
                           │ (Upload KTP)
                           v
                    ┌──────────────┐
                    │   Go API     │ (Verifikasi Ukuran/Tipe)
                    └──────┬───────┘
                           │
             (1) Save Data │ (2) PutObject
                           v
         ┌──────────────┐      ┌──────────────┐
         │ PostgreSQL   │      │    MinIO     │
         └──────────────┘      └──────────────┘

1. User upload KTP (gambar) lewat React.
2. Go API menerima. Generate UUID: kyc-documents/user-99/ktp-ab12cd.jpg.
3. Go API melempar file tersebut ke MinIO ke bucket bank-private.
4. Go API menyimpan object_key tersebut ke PostgreSQL di tabel user_kyc.
5. Saat tim admin bank mau lihat KTP tersebut lewat internal dashboard, Go API men-generate Presigned URL yang valid selama 30 menit dan mengirimkannya ke dashboard.

MinIO + Kubernetes

• Persistent Volume (PV) & Persistent Volume Claim (PVC): Ini untuk meminta "Hard disk" permanen dari cloud provider (misal AWS EBS atau GCP Persistent Disk) agar menempel ke Pod MinIO.
• StatefulSet: MinIO di-deploy bukan sebagai Deployment biasa, melainkan StatefulSet agar network identity dan urutan disk-nya terjaga.

Kapan Menggunakan MinIO dan Kapan Tidak?

• Kamu membutuhkan abstraksi S3 API untuk fleksibilitas di masa depan.
• Kamu butuh fitur Presigned URL untuk keamanan file private.
• Kamu ingin self-host object storage di VPS karena biaya AWS S3 terlalu mahal untuk bandwidth aplikasimu.
• Aplikasimu di-deploy menggunakan Docker atau Kubernetes (arsitektur stateless).
• Kamu berurusan dengan banyak aset statis/biner (gambar, PDF, video).

• Aplikasimu hanya blog WordPress sederhana atau web profil perusahaan yang statis.
• Kamu hanya perlu menyimpan 10-20 gambar kecil.
• Kamu menghindari operational complexity (tidak mau pusing me-maintain container tambahan).

Mental Model yang Harus Dipahami Junior

Application ---> HTTP (S3 Protocol) ---> Object Storage (MinIO)
                                              |
                                              +--- Bucket (Namespace)
                                              +--- Object (File)
                                              +--- Metadata
                                              +--- Policy (Izin Akses)

Best Practice Checklist

• [ ] Bucket strategy sudah jelas (mana yang public, mana yang private).
• [ ] Object key menggunakan UUID atau identifier unik, tidak pernah original file name.
• [ ] Kredensial (Access/Secret Key) tidak di-hardcode di source code, melainkan pakai .env.
• [ ] HTTPS/SSL diaktifkan di sisi MinIO atau melalui Nginx (Production).
• [ ] Database men-tracking informasi object key dan bucket.
• [ ] Akses file private secara ketat menggunakan Presigned URL.
• [ ] Menggunakan Persistent Volume di Docker/K8s.
• [ ] Ukuran upload maksimal (file size limit) diaktifkan di Backend/Reverse Proxy.
• [ ] MIME type dan ektensi file divalidasi dengan ketat di Backend sebelum diteruskan ke MinIO.
• [ ] Menggunakan akun IAM / User Policy khusus (bukan root user) untuk aplikasi.

Kesimpulan

• Application Server (Laravel/Go) khusus menangani komputasi dan business logic.
• Database (PostgreSQL/MySQL) khusus menangani data terstruktur dan relasional.
• Object Storage (MinIO/S3) khusus menangani bongkahan file binary (gambar, dokumen).