MinIO Docker: guida all’installazione per lo storage a oggetti compatibile con S3
Esegui MinIO con Docker per ottenere storage a oggetti compatibile con S3 per lo sviluppo locale, con setup, volumi persistenti, troubleshooting e quando usare la modalità distribuita.
Ti serve uno storage a oggetti per lo sviluppo, ma non vuoi configurare e pagare AWS S3?
MinIO ti offre storage compatibile con S3 che gira ovunque: sul tuo laptop, su una VM o in un cluster Kubernetes. È open source, quindi è indipendente dal fornitore e non riceverai brutte sorprese in bolletta a fine mese. E insieme a Docker, far girare MinIO è ancora più semplice, perché puoi avviare un server di storage in pochi secondi senza installare nulla direttamente sulla tua macchina.
I container Docker tengono MinIO isolato dal sistema e allo stesso tempo ti danno il pieno controllo su configurazione e persistenza dei dati. Puoi testare le API S3 in locale, simulare setup di storage in produzione o eseguire uno storage a oggetti leggero per progetti piccoli.
In questo articolo ti mostro come eseguire MinIO con Docker, verificare che funzioni correttamente e configurare le opzioni di setup più comuni.
Se sei completamente nuovo a Docker, dedica un pomeriggio di sabato per padroneggiare le basi: il corso Introduction to Docker di DataCamp fa per te.
Prerequisiti
Ti servono tre cose per eseguire MinIO con Docker.
Docker installato e in esecuzione sulla tua macchina. Puoi verificarlo eseguendo docker --version nel terminale. Se ottieni un numero di versione, sei a posto.
Conoscenza di base dei comandi Docker. Dovresti sapere come avviare e fermare container, visualizzare i log e lavorare con le immagini Docker. Se hai già eseguito docker run o lavorato con Docker Compose, sei a posto.
Una directory locale per lo storage persistente. MinIO ha bisogno di un posto dove salvare i tuoi dati fuori dal container. Crea una directory vuota sulla tua macchina host, ad esempio ~/minio/data va benissimo.
Tutto qui. La lista è breve e semplice, ma assicurati di spuntare tutte le voci prima di proseguire.
Come eseguire MinIO con Docker (setup single-node)
Un setup MinIO single-node esegue un’istanza di MinIO in un container Docker e memorizza tutti i dati in un’unica posizione.
Questo setup va bene per sviluppo, test e workload di produzione su piccola scala in cui non ti serve alta disponibilità o storage distribuito. Ottieni piena compatibilità con le API S3 senza la complessità di gestire più nodi.
Eseguire MinIO con Docker Run
Il comando docker run avvia MinIO in un nuovo container con tutto configurato in un’unica riga.
Ecco il comando di base:
docker run -p9000:9000 -p9001:9001 \--name minio \-v ~/minio/data:/data \-e"MINIO_ROOT_USER=admin"\-e"MINIO_ROOT_PASSWORD=password123"\
quay.io/minio/minio server /data --console-address ":9001"Offerto da
Esecuzione di MinIO con docker run
Vediamo nel dettaglio cosa fa ogni parte.
La porta 9000 è l’endpoint API a cui si collegano le applicazioni per caricare e scaricare file. Qui è dove i client compatibili con S3 inviano le richieste.
La porta 9001 ospita la console web da cui gestisci bucket, permessi e monitoraggio dello storage. La userai per verificare che MinIO funzioni correttamente.
Il flag -v ~/minio/data:/data mappa la tua directory locale sulla posizione di storage del container. Tutto ciò che MinIO salva finisce in ~/minio/data sulla tua macchina host. Quando fermi o rimuovi il container, i dati restano al sicuro in questa directory.
Le variabili d’ambiente impostano le credenziali di accesso. MINIO_ROOT_USER è il tuo username admin e MINIO_ROOT_PASSWORD è la password. Sono le credenziali che userai per accedere alla console web e configurare l’accesso API.
L’argomento server /data indica a MinIO di avviarsi in modalità server e usare /data come directory di storage. Il flag --console-address ":9001" specifica la porta su cui la console web resta in ascolto.
C’è un modo alternativo per eseguire MinIO, ottimo se non ami i comandi da terminale lunghi e multi-riga.
Nota: MinIO non aggiorna più le immagini su Docker Hub e Quay (da ottobre 2025). Il codice in questo articolo funziona ancora per lo sviluppo locale, ma per la produzione valuta alternative mantenute come l’immagine MinIO di Chainguard (cgr.dev/chainguard/minio:latest).
Eseguire MinIO con Docker Compose
Docker Compose ti permette di definire il setup di MinIO in un file YAML invece di digitare comandi lunghi.
Questo rende la configurazione ripetibile e versionata. Puoi condividere il file con il tuo team, farne il commit su git e riavviare MinIO con le stesse identiche impostazioni ogni volta.
Crea un file docker-compose.yml:
services:minio:image: quay.io/minio/minio
container_name: minio
ports:-"9000:9000"-"9001:9001"environment:MINIO_ROOT_USER: admin
MINIO_ROOT_PASSWORD: password123
volumes:- ./minio/data:/data
command: server /data --console-address ":9001"Offerto da
La struttura rispecchia il comando docker run ma organizza tutto in sezioni nominate. Porte, variabili d’ambiente e volumi hanno ciascuno il proprio blocco.
Il mapping del volume funziona allo stesso modo: ./minio/data:/data crea una directory nella cartella corrente e la monta nel container. Il ./ indica il percorso relativo alla posizione del file docker-compose.yml.
Il flag -d esegue il container in background. Il tuo terminale non sarà bloccato dai log di MinIO e il container continuerà a girare anche dopo la chiusura del terminale.
Compose è migliore per lo sviluppo perché puoi aggiungere healthcheck, policy di riavvio e più servizi nello stesso file. Se più avanti ti serve aggiungere un database o altri servizi insieme a MinIO, basta aggiungere altre voci sotto services:.
Come accedere e verificare che MinIO sia in esecuzione
Ora che MinIO è in funzione, vuoi confermare che si sia avviato correttamente prima di usarlo per lo storage.
Ci sono due modi per verificare il setup: la console web per una conferma visiva e il client MinIO per una verifica da riga di comando.
Usare la console web di MinIO
Apri il browser e vai su http://localhost:9001.
Vedrai una schermata di login che chiede le credenziali:
Interfaccia web MinIO
Puoi accedere con le credenziali fornite come variabili d’ambiente: admin/password123 nel mio caso.
Dopo l’accesso, atterrerai sulla dashboard di MinIO. La pagina principale mostra l’uso dello storage, il numero di bucket e lo stato del sistema. La barra laterale sinistra offre opzioni per creare bucket, gestire utenti e visualizzare metriche.
Creazione di un bucket tramite l’interfaccia web di MinIO
Crea un bucket di test per verificare che tutto funzioni. Clicca su "Buckets" nella sidebar, poi su "Create Bucket". Assegnagli un nome, ad esempio test-bucket, e conferma. Se il bucket appare nell’elenco, MinIO è attivo e sta memorizzando i dati.
Creazione di un bucket tramite l’interfaccia web di MinIO
Usare il client MinIO (mc)
Il client MinIO è uno strumento da riga di comando che ti permette di interagire con MinIO come faresti con AWS CLI.
Se vedi test.txt nell’output, hai configurato tutto correttamente.
Elencare i file in un bucket
Ecco qualche rapido troubleshooting se qualcosa non funziona:
Controlla se il container è in esecuzione con docker ps. Se non vedi un container chiamato minio, non è partito o è andato in crash.
Visualizza i log con docker logs minio. Cerca errori su porte già in uso o problemi di permessi sulla directory dei dati.
Se non riesci ad accedere alla console web, verifica che le porte non siano bloccate controllando con docker port minio. Dovresti vedere sia 9000 che 9001 mappate correttamente.
Se riscontri errori di permessi sulla directory dei dati, esegui chmod -R 755 ~/minio/data per risolvere i problemi di accesso.
Storage persistente e data volume
Per impostazione predefinita i container sono effimeri: quando rimuovi un container, tutto ciò che è al suo interno scompare.
MinIO memorizza oggetti, metadati e file di configurazione. Se non imposti correttamente lo storage persistente, perderai tutti i dati non appena riavvii o rimuovi il container.
Usare volumi locali con Docker
I volumi Docker e i bind mount tengono al sicuro i tuoi dati al di fuori del container.
Quando usi -v ~/minio/data:/data o mappi un volume in Docker Compose, MinIO scrive tutto sulla tua macchina host. Il container legge e scrive file su /data, ma quei file in realtà vivono in ~/minio/data sull’host.
Quando fermi il container, lo rimuovi o persino cancelli l’immagine, i tuoi dati restano in ~/minio/data. Avvia un nuovo container MinIO puntando alla stessa directory e tutti i tuoi bucket, oggetti e impostazioni torneranno esattamente come li avevi lasciati.
Se non mappi un volume, MinIO usa il filesystem interno del container. Tutto funziona finché non fermi il container. Al riavvio, MinIO riparte da zero: niente bucket, niente oggetti e nessuna configurazione.
L’esempio con compose che ti ho mostrato prima crea una cartella minio/data proprio dove si trova il file compose:
Cartella dati di MinIO
Errori comuni con lo storage
Eseguire senza un volume è l’errore più comune.
Avvii MinIO, carichi file, crei bucket e tutto sembra a posto. Poi riavvii il container per un aggiornamento o un cambio di configurazione. Tutti i dati sono spariti perché erano salvati dentro il container, non sull’host.
Controlla sempre che il tuo comando Docker o file Compose abbia un mapping di volume prima di mettere dati reali in MinIO.
Problemi di permessi si verificano quando Docker non può scrivere nella directory montata.
Il processo MinIO dentro il container gira come un utente specifico. Se quell’utente non ha permessi di scrittura sulla directory dell’host, MinIO va in crash all’avvio o fallisce silenziosamente quando prova a salvare oggetti.
Puoi risolvere assicurandoti che la directory dei dati sia scrivibile:
Morale: configura bene i volumi una volta e non dovrai preoccuparti di perdere dati.
Variabili d’ambiente e configurazione di base
MinIO legge la configurazione dalle variabili d’ambiente all’avvio.
Questo significa che puoi cambiare il comportamento di MinIO senza modificare file di config o ricostruire i container. Imposti queste variabili nel comando docker run o nel file Docker Compose.
Access key e credenziali
MinIO richiede due variabili d’ambiente per l’autenticazione: MINIO_ROOT_USER e MINIO_ROOT_PASSWORD.
Queste creano l’account admin root con pieno controllo sulla tua istanza MinIO. L’utente root può creare bucket, gestire altri utenti, impostare policy e accedere a tutti gli oggetti memorizzati.
Impostale così durante docker run:
-e"MINIO_ROOT_USER=admin"\-e"MINIO_ROOT_PASSWORD=your-secure-password"Offerto da
Oppure in Docker Compose:
environment:
MINIO_ROOT_USER: admin
MINIO_ROOT_PASSWORD: your-secure-passwordOfferto da
Non usare credenziali di default in produzione. Gli esempi in questo articolo usano admin e password123 per semplicità, ma sono pessime scelte per deployment reali.
Scegli una password robusta di almeno 8 caratteri. Ancora meglio, usa credenziali generate casualmente e conservale in un password manager o in un sistema di gestione dei segreti.
Non inserire in hardcode le credenziali nei file Docker Compose che mandi in version control. Usa invece file di ambiente:
environment:
MINIO_ROOT_USER: ${MINIO_ROOT_USER}
MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}Offerto da
Poi crea un file .env con le tue credenziali reali e aggiungilo a .gitignore.
Configurazione delle porte e networking
MinIO necessita di due porte per funzionare correttamente.
Porta 9000 gestisce le API S3. Qui le applicazioni inviano richieste per memorizzare e recuperare oggetti. Tutti i client compatibili con S3 si connettono a questa porta.
Porta 9001 serve la console web. È l’interfaccia browser con cui gestisci MinIO tramite GUI.
Ora l’API di MinIO è su http://localhost:9090 e la console su http://localhost:9091. Il container usa ancora internamente 9000 e 9001, ma esternamente accedi tramite porte diverse.
Questi comandi ti aiutano a controllare cosa sta usando una porta prima di avviare MinIO:
Se esegui più istanze MinIO sulla stessa macchina, assegna a ciascuna mapping di porte univoci per evitare conflitti.
Eseguire MinIO in modalità distribuita con Docker
La modalità distribuita esegue MinIO su più server con più dischi per alta disponibilità e ridondanza dei dati.
Per sviluppo o test non ti serve. La modalità single-node copre benissimo la maggior parte dei casi. Salta questa sezione a meno che tu non stia pianificando un deployment in produzione che deve restare online anche in caso di guasti.
Quando ha senso MinIO distribuito
Usa la modalità distribuita quando ti serve tolleranza ai guasti.
Se un server si guasta in un setup distribuito, MinIO continua a funzionare e i dati restano accessibili. Il sistema usa l’erasure coding per suddividere gli oggetti su più dischi e server, quindi puoi perdere dischi o interi nodi senza perdere i dati.
Serve anche per storage su larga scala. Se archivi terabyte o petabyte di dati, distribuirli su più macchine ti dà migliori prestazioni e più capacità rispetto a un singolo server.
Per lo sviluppo locale non serve nulla di tutto questo. La modalità distribuita aggiunge complessità: ti servono più macchine o VM, networking coordinato e una configurazione attenta dei dischi. Per testare le API S3 o eseguire storage a oggetti sul laptop, la modalità single-node fa tutto ciò che ti serve.
Gli ambienti di produzione usano la modalità distribuita quando i downtime non sono accettabili e la perdita di dati sarebbe catastrofica. Pensa a sistemi di backup, data lake o applicazioni in cui gli utenti dipendono da uno storage sempre disponibile.
Panoramica del setup ad alto livello
MinIO distribuito richiede almeno quattro dischi su più nodi.
Ogni nodo esegue un container MinIO e tutti i nodi devono vedere la stessa configurazione dei dischi. Non puoi mescolare nodi a singolo disco con nodi multi-disco né cambiare il numero di dischi dopo il setup.
Un setup distribuito di base assomiglia a questo:
Quattro server (o VM) con MinIO installato
Più dischi su ogni server dedicati a MinIO
Connettività di rete tra tutti i nodi
Percorsi dei dischi identici su ogni nodo
Puoi gestire il coordinamento in un unico file Compose, ma ti avverto: sarà lungo. Devi definire tutti i nodi, impostare i percorsi dei dischi e avviarli insieme.
Ecco un esempio completo per quattro nodi con due dischi ciascuno:
La sintassi {1...4} indica a MinIO di connettersi a quattro nodi (minio1 a minio4) con due dischi ciascuno (data1 e data2). Ogni nodo ha mapping di porte unici così puoi accedervi singolarmente: il nodo 1 usa 9001/9091, il nodo 2 usa 9002/9092 e così via.
La rete minio-distributed permette ai container di raggiungersi per hostname. Tutti i nodi devono usare le stesse credenziali e vedere lo stesso layout dei dischi.
Per avviare il cluster, prima crea le directory dei dati e poi esegui il file compose
mkdir-p data/minio{1..4}/data{1..2}docker compose up -dOfferto da
Esecuzione di MinIO in modalità distribuita
Tutto qui! Ora puoi visitare uno qualsiasi dei seguenti URL per accedere alla web UI:
Ma di nuovo, non costruire tutto questo a meno che non ti serva davvero: la modalità distribuita è per workload di produzione in cui uptime e ridondanza giustificano la complessità extra.
Inoltre, probabilmente vorrai cose come TLS, un endpoint console unico, volumi/dischi esterni per un ambiente di produzione completo.
Problemi comuni nell’esecuzione di MinIO in Docker
La maggior parte dei problemi con MinIO su Docker deriva da volumi, porte o credenziali configurati male.
Ecco i problemi che incontrerai davvero e come risolverli rapidamente.
Il container parte ma la web UI non è accessibile
Esegui docker ps e vedi il container in esecuzione, ma http://localhost:9001 non risponde o va in timeout.
Per risolvere, controlla prima che la porta della console sia mappata correttamente:
Cerca la riga che dice "Console: http://..." — ti indica su quale indirizzo MinIO sta davvero ascoltando. Se vedi una porta diversa da quella prevista, potresti aver impostato male il flag --console-address.
Errori di permessi sui volumi montati
MinIO va in crash all’avvio o nei log vedi errori "permission denied" quando prova a scrivere su /data.
Il processo MinIO gira come un utente specifico nel container e quell’utente deve avere accesso in scrittura alla directory montata. Risolvi con:
Cerca MINIO_ROOT_USER e MINIO_ROOT_PASSWORD nell’output. Se mancano, hai dimenticato i flag -e o la sezione environment: nel file Compose.
MinIO richiede anche password di almeno 8 caratteri. Se la tua è più corta, il container potrebbe rifiutarla o usarne una di default.
Se hai cambiato le credenziali su un setup esistente, ferma e rimuovi completamente il container, poi riparti da zero:
docker stop minio
dockerrm minio
docker run ... # with new credentialsOfferto da
Vecchi file di credenziali potrebbero persistere nella directory dei dati e causare conflitti.
Best practice per eseguire MinIO con Docker
Segui queste pratiche per evitare errori comuni e mantenere gestibile il tuo setup MinIO.
Usa Docker Compose per la ripetibilità. Un file Compose documenta la tua configurazione esatta: porte, volumi, variabili d’ambiente e comandi. Puoi versionarlo, condividerlo con il team e ricreare setup identici su macchine diverse. Eseguire lunghi comandi docker run dalla cronologia della shell porta a drift di configurazione ed errori.
Configura sempre lo storage persistente. Mappa un volume o un bind mount prima di salvare dati reali. I container sono effimeri: se salti questo passaggio, perderai tutto al riavvio del container. Verifica la configurazione con docker inspect minio e controlla che il mapping del volume sia corretto.
Tieni le credenziali fuori dalla cronologia dei comandi. Non inserire le password direttamente nei comandi docker run o nei file Compose che mandi su git. Usa file di ambiente (.env) con Docker Compose o passa le credenziali tramite variabili d’ambiente a runtime. Aggiungi subito .env al tuo .gitignore.
Usa la modalità single-node solo per lo sviluppo. La modalità distribuita è complessa e lenta da configurare. Non ti servono alta disponibilità o erasure coding sul laptop. Riserva i deployment distribuiti alla produzione, dove il downtime conta davvero.
Monitora i log durante l’avvio. Esegui docker logs -f minio al primo avvio di MinIO. I log mostrano l’endpoint API, l’URL della console e gli eventuali errori di configurazione. Se qualcosa non va, lo vedrai subito invece di chiederti perché nulla funziona.
Segui queste pratiche e il tuo setup MinIO sarà solido dal primo giorno.
Conclusione
Eseguire MinIO con Docker significa avere storage a oggetti compatibile con S3 sulla tua macchina in meno di un minuto.
Per sviluppo, test e progetti su piccola scala, MinIO single-node in Docker ti dà tutto ciò che serve. Ottieni piena compatibilità con le API S3, una console web per la gestione e il controllo totale sui tuoi dati senza dipendere dai servizi cloud o pagare per storage che non usi.
Parti dalle basi: un semplice comando docker run o un file Docker Compose con volumi persistenti e credenziali sicure (meglio il secondo). Testa il setup, verifica che funzioni e aggiungi complessità solo quando ti serve davvero.
La modalità distribuita, l’alta disponibilità e le configurazioni di livello production esistono per un motivo — ma quel motivo non è lo sviluppo locale. Passa a quei setup quando distribuisci in produzione, quando il downtime ti costa denaro o quando stai archiviando dati che non possono andare persi. Fino ad allora, tieni tutto semplice e concentrati a costruire la tua applicazione invece che a gestire l’infrastruttura.
Senior Data Scientist con base in Croazia. Top Tech Writer con oltre 700 articoli pubblicati, per più di 10 milioni di visualizzazioni. Autore del libro Machine Learning Automation with TPOT.
FAQs
Come posso ottimizzare le prestazioni di MinIO per upload ad alta concorrenza?⌄
Aumenta il numero di connessioni concorrenti che il tuo server MinIO può gestire regolando la variabile d’ambiente MINIO_API_REQUESTS_MAX. Per carichi ad alta concorrenza, valuta anche l’uso di più dischi nel setup, poiché MinIO distribuisce automaticamente il carico tra i dischi disponibili. Se usi la modalità distribuita, assicurati che la banda di rete tra i nodi regga il traffico e usa interfacce di rete dedicate alla comunicazione MinIO.
Quali sono le best practice per configurare MinIO con Docker Compose?⌄
Usa sempre Docker Compose invece dei comandi docker run per setup di tipo production, perché rende la configurazione ripetibile e versionata. Conserva le credenziali in un file separato .env e aggiungilo a .gitignore per tenere i segreti fuori dal repository. Mappa volumi persistenti su directory dedicate dell’host, imposta policy di riavvio su unless-stopped o always e includi healthcheck per monitorare lo stato del container.
Come configuro MinIO per un accesso sicuro tramite TLS?⌄
Genera i certificati TLS e posizionali in una directory sull’host, poi monta quella directory in /root/.minio/certs dentro il container MinIO. MinIO rileva automaticamente i certificati in questa posizione e abilita HTTPS all’avvio. Ti serviranno un file public.crt per il certificato e un file private.key per la chiave privata, e il certificato deve corrispondere all’hostname o all’IP del server MinIO.
Quali sono le principali differenze tra MinIO e altre alternative compatibili con S3?⌄
MinIO è completamente open source e progettato specificamente per lo storage a oggetti ad alte prestazioni, mentre molte alternative compatibili con S3 sono servizi cloud o hanno set di funzionalità limitati. MinIO supporta funzionalità come erasure coding distribuito, versioning, crittografia e policy di ciclo di vita in linea con le capacità di AWS S3. A differenza di alcune alternative, MinIO gira ovunque — bare metal, VM, container o Kubernetes — e non ti vincola a un cloud provider specifico.
Come posso automatizzare i processi di backup e ripristino di MinIO?⌄
Usa il client MinIO (mc) per creare script che effettuano il mirroring dei bucket verso un’altra istanza MinIO o uno storage compatibile con S3 con mc mirror source/ destination/. Pianifica questi script con cron job oppure usa la funzionalità integrata di replica dei bucket di MinIO per sincronizzare automaticamente i dati tra istanze MinIO. Per i ripristini, usa mc mirror al contrario per copiare i dati dalla posizione di backup, o mc cp con il flag --recursive per ripristinare bucket o oggetti specifici.
Scopri i 15 migliori server MCP remoti che stanno trasformando lo sviluppo AI nel 2026. Scopri come migliorano automazione, ragionamento, sicurezza e velocità dei workflow.
Ti serve uno storage a oggetti per lo sviluppo, ma non vuoi configurare e pagare AWS S3?
MinIO ti offre storage compatibile con S3 che gira ovunque: sul tuo laptop, su una VM o in un cluster Kubernetes. È open source, quindi è indipendente dal fornitore e non riceverai brutte sorprese in bolletta a fine mese. E insieme a Docker, far girare MinIO è ancora più semplice, perché puoi avviare un server di storage in pochi secondi senza installare nulla direttamente sulla tua macchina.
I container Docker tengono MinIO isolato dal sistema e allo stesso tempo ti danno il pieno controllo su configurazione e persistenza dei dati. Puoi testare le API S3 in locale, simulare setup di storage in produzione o eseguire uno storage a oggetti leggero per progetti piccoli.
In questo articolo ti mostro come eseguire MinIO con Docker, verificare che funzioni correttamente e configurare le opzioni di setup più comuni.
Se sei completamente nuovo a Docker, dedica un pomeriggio di sabato per padroneggiare le basi: il corso Introduction to Docker di DataCamp fa per te.
Prerequisiti
Ti servono tre cose per eseguire MinIO con Docker.
Docker installato e in esecuzione sulla tua macchina. Puoi verificarlo eseguendo
docker --versionnel terminale. Se ottieni un numero di versione, sei a posto.Conoscenza di base dei comandi Docker. Dovresti sapere come avviare e fermare container, visualizzare i log e lavorare con le immagini Docker. Se hai già eseguito
docker runo lavorato con Docker Compose, sei a posto.Una directory locale per lo storage persistente. MinIO ha bisogno di un posto dove salvare i tuoi dati fuori dal container. Crea una directory vuota sulla tua macchina host, ad esempio
~/minio/datava benissimo.Tutto qui. La lista è breve e semplice, ma assicurati di spuntare tutte le voci prima di proseguire.
Come eseguire MinIO con Docker (setup single-node)
Un setup MinIO single-node esegue un’istanza di MinIO in un container Docker e memorizza tutti i dati in un’unica posizione.
Questo setup va bene per sviluppo, test e workload di produzione su piccola scala in cui non ti serve alta disponibilità o storage distribuito. Ottieni piena compatibilità con le API S3 senza la complessità di gestire più nodi.
Eseguire MinIO con Docker Run
Il comando
docker runavvia MinIO in un nuovo container con tutto configurato in un’unica riga.Ecco il comando di base:
Esecuzione di MinIO con docker run
Vediamo nel dettaglio cosa fa ogni parte.
La porta 9000 è l’endpoint API a cui si collegano le applicazioni per caricare e scaricare file. Qui è dove i client compatibili con S3 inviano le richieste.
La porta 9001 ospita la console web da cui gestisci bucket, permessi e monitoraggio dello storage. La userai per verificare che MinIO funzioni correttamente.
Il flag
-v ~/minio/data:/datamappa la tua directory locale sulla posizione di storage del container. Tutto ciò che MinIO salva finisce in~/minio/datasulla tua macchina host. Quando fermi o rimuovi il container, i dati restano al sicuro in questa directory.Le variabili d’ambiente impostano le credenziali di accesso.
MINIO_ROOT_USERè il tuo username admin eMINIO_ROOT_PASSWORDè la password. Sono le credenziali che userai per accedere alla console web e configurare l’accesso API.L’argomento
server /dataindica a MinIO di avviarsi in modalità server e usare/datacome directory di storage. Il flag--console-address ":9001"specifica la porta su cui la console web resta in ascolto.C’è un modo alternativo per eseguire MinIO, ottimo se non ami i comandi da terminale lunghi e multi-riga.
Nota: MinIO non aggiorna più le immagini su Docker Hub e Quay (da ottobre 2025). Il codice in questo articolo funziona ancora per lo sviluppo locale, ma per la produzione valuta alternative mantenute come l’immagine MinIO di Chainguard (cgr.dev/chainguard/minio:latest).
Eseguire MinIO con Docker Compose
Docker Compose ti permette di definire il setup di MinIO in un file YAML invece di digitare comandi lunghi.
Questo rende la configurazione ripetibile e versionata. Puoi condividere il file con il tuo team, farne il commit su git e riavviare MinIO con le stesse identiche impostazioni ogni volta.
Crea un file
docker-compose.yml:La struttura rispecchia il comando
docker runma organizza tutto in sezioni nominate. Porte, variabili d’ambiente e volumi hanno ciascuno il proprio blocco.Il mapping del volume funziona allo stesso modo:
./minio/data:/datacrea una directory nella cartella corrente e la monta nel container. Il./indica il percorso relativo alla posizione del filedocker-compose.yml.Ora puoi avviare MinIO con:
Esecuzione di MinIO con docker compose
Il flag
-desegue il container in background. Il tuo terminale non sarà bloccato dai log di MinIO e il container continuerà a girare anche dopo la chiusura del terminale.Per fermarlo:
Compose è migliore per lo sviluppo perché puoi aggiungere healthcheck, policy di riavvio e più servizi nello stesso file. Se più avanti ti serve aggiungere un database o altri servizi insieme a MinIO, basta aggiungere altre voci sotto
services:.Come accedere e verificare che MinIO sia in esecuzione
Ora che MinIO è in funzione, vuoi confermare che si sia avviato correttamente prima di usarlo per lo storage.
Ci sono due modi per verificare il setup: la console web per una conferma visiva e il client MinIO per una verifica da riga di comando.
Usare la console web di MinIO
Apri il browser e vai su
http://localhost:9001.Vedrai una schermata di login che chiede le credenziali:
Interfaccia web MinIO
Puoi accedere con le credenziali fornite come variabili d’ambiente:
admin/password123nel mio caso.Dopo l’accesso, atterrerai sulla dashboard di MinIO. La pagina principale mostra l’uso dello storage, il numero di bucket e lo stato del sistema. La barra laterale sinistra offre opzioni per creare bucket, gestire utenti e visualizzare metriche.
Creazione di un bucket tramite l’interfaccia web di MinIO
Crea un bucket di test per verificare che tutto funzioni. Clicca su "Buckets" nella sidebar, poi su "Create Bucket". Assegnagli un nome, ad esempio
test-bucket, e conferma. Se il bucket appare nell’elenco, MinIO è attivo e sta memorizzando i dati.Creazione di un bucket tramite l’interfaccia web di MinIO
Usare il client MinIO (mc)
Il client MinIO è uno strumento da riga di comando che ti permette di interagire con MinIO come faresti con AWS CLI.
Esegui uno di questi comandi per installarlo:
Ora esegui questo comando per collegare il client alla tua istanza MinIO locale:
Questo crea un alias chiamato
localche punta al tuo server MinIO. Ora puoi eseguire comandi contro di esso.Elenca i tuoi bucket:
Elencare i bucket
Se hai creato il bucket di test prima, lo vedrai nell’output. Se il comando restituisce vuoto o mostra i tuoi bucket, MinIO funziona.
Ora puoi caricare un file di test nel bucket:
E poi verificare che ci sia:
Se vedi
test.txtnell’output, hai configurato tutto correttamente.Elencare i file in un bucket
Ecco qualche rapido troubleshooting se qualcosa non funziona:
Controlla se il container è in esecuzione con
docker ps. Se non vedi un container chiamatominio, non è partito o è andato in crash.Visualizza i log con
docker logs minio. Cerca errori su porte già in uso o problemi di permessi sulla directory dei dati.Se non riesci ad accedere alla console web, verifica che le porte non siano bloccate controllando con
docker port minio. Dovresti vedere sia 9000 che 9001 mappate correttamente.Se riscontri errori di permessi sulla directory dei dati, esegui
chmod -R 755 ~/minio/dataper risolvere i problemi di accesso.Storage persistente e data volume
Per impostazione predefinita i container sono effimeri: quando rimuovi un container, tutto ciò che è al suo interno scompare.
MinIO memorizza oggetti, metadati e file di configurazione. Se non imposti correttamente lo storage persistente, perderai tutti i dati non appena riavvii o rimuovi il container.
Usare volumi locali con Docker
I volumi Docker e i bind mount tengono al sicuro i tuoi dati al di fuori del container.
Quando usi
-v ~/minio/data:/datao mappi un volume in Docker Compose, MinIO scrive tutto sulla tua macchina host. Il container legge e scrive file su/data, ma quei file in realtà vivono in~/minio/datasull’host.Quando fermi il container, lo rimuovi o persino cancelli l’immagine, i tuoi dati restano in
~/minio/data. Avvia un nuovo container MinIO puntando alla stessa directory e tutti i tuoi bucket, oggetti e impostazioni torneranno esattamente come li avevi lasciati.Se non mappi un volume, MinIO usa il filesystem interno del container. Tutto funziona finché non fermi il container. Al riavvio, MinIO riparte da zero: niente bucket, niente oggetti e nessuna configurazione.
L’esempio con compose che ti ho mostrato prima crea una cartella
minio/dataproprio dove si trova il file compose:Cartella dati di MinIO
Errori comuni con lo storage
Eseguire senza un volume è l’errore più comune.
Avvii MinIO, carichi file, crei bucket e tutto sembra a posto. Poi riavvii il container per un aggiornamento o un cambio di configurazione. Tutti i dati sono spariti perché erano salvati dentro il container, non sull’host.
Controlla sempre che il tuo comando Docker o file Compose abbia un mapping di volume prima di mettere dati reali in MinIO.
Problemi di permessi si verificano quando Docker non può scrivere nella directory montata.
Il processo MinIO dentro il container gira come un utente specifico. Se quell’utente non ha permessi di scrittura sulla directory dell’host, MinIO va in crash all’avvio o fallisce silenziosamente quando prova a salvare oggetti.
Puoi risolvere assicurandoti che la directory dei dati sia scrivibile:
Oppure esegui il container con un utente che corrisponde al tuo utente host:
Morale: configura bene i volumi una volta e non dovrai preoccuparti di perdere dati.
Variabili d’ambiente e configurazione di base
MinIO legge la configurazione dalle variabili d’ambiente all’avvio.
Questo significa che puoi cambiare il comportamento di MinIO senza modificare file di config o ricostruire i container. Imposti queste variabili nel comando
docker runo nel file Docker Compose.Access key e credenziali
MinIO richiede due variabili d’ambiente per l’autenticazione:
MINIO_ROOT_USEReMINIO_ROOT_PASSWORD.Queste creano l’account admin root con pieno controllo sulla tua istanza MinIO. L’utente root può creare bucket, gestire altri utenti, impostare policy e accedere a tutti gli oggetti memorizzati.
Impostale così durante
docker run:Oppure in Docker Compose:
Non usare credenziali di default in produzione. Gli esempi in questo articolo usano
adminepassword123per semplicità, ma sono pessime scelte per deployment reali.Scegli una password robusta di almeno 8 caratteri. Ancora meglio, usa credenziali generate casualmente e conservale in un password manager o in un sistema di gestione dei segreti.
Non inserire in hardcode le credenziali nei file Docker Compose che mandi in version control. Usa invece file di ambiente:
Poi crea un file
.envcon le tue credenziali reali e aggiungilo a.gitignore.Configurazione delle porte e networking
MinIO necessita di due porte per funzionare correttamente.
Mappa queste porte nel comando Docker:
I conflitti di porta capitano quando un altro servizio usa già la 9000 o la 9001 sull’host.
All’avvio del container vedrai un errore tipo "bind: address already in use". Risolvi mappando su porte host diverse:
Ora l’API di MinIO è su
http://localhost:9090e la console suhttp://localhost:9091. Il container usa ancora internamente 9000 e 9001, ma esternamente accedi tramite porte diverse.Questi comandi ti aiutano a controllare cosa sta usando una porta prima di avviare MinIO:
Controllo di cosa usa una porta
Se esegui più istanze MinIO sulla stessa macchina, assegna a ciascuna mapping di porte univoci per evitare conflitti.
Eseguire MinIO in modalità distribuita con Docker
La modalità distribuita esegue MinIO su più server con più dischi per alta disponibilità e ridondanza dei dati.
Per sviluppo o test non ti serve. La modalità single-node copre benissimo la maggior parte dei casi. Salta questa sezione a meno che tu non stia pianificando un deployment in produzione che deve restare online anche in caso di guasti.
Quando ha senso MinIO distribuito
Usa la modalità distribuita quando ti serve tolleranza ai guasti.
Se un server si guasta in un setup distribuito, MinIO continua a funzionare e i dati restano accessibili. Il sistema usa l’erasure coding per suddividere gli oggetti su più dischi e server, quindi puoi perdere dischi o interi nodi senza perdere i dati.
Serve anche per storage su larga scala. Se archivi terabyte o petabyte di dati, distribuirli su più macchine ti dà migliori prestazioni e più capacità rispetto a un singolo server.
Per lo sviluppo locale non serve nulla di tutto questo. La modalità distribuita aggiunge complessità: ti servono più macchine o VM, networking coordinato e una configurazione attenta dei dischi. Per testare le API S3 o eseguire storage a oggetti sul laptop, la modalità single-node fa tutto ciò che ti serve.
Gli ambienti di produzione usano la modalità distribuita quando i downtime non sono accettabili e la perdita di dati sarebbe catastrofica. Pensa a sistemi di backup, data lake o applicazioni in cui gli utenti dipendono da uno storage sempre disponibile.
Panoramica del setup ad alto livello
MinIO distribuito richiede almeno quattro dischi su più nodi.
Ogni nodo esegue un container MinIO e tutti i nodi devono vedere la stessa configurazione dei dischi. Non puoi mescolare nodi a singolo disco con nodi multi-disco né cambiare il numero di dischi dopo il setup.
Un setup distribuito di base assomiglia a questo:
Puoi gestire il coordinamento in un unico file Compose, ma ti avverto: sarà lungo. Devi definire tutti i nodi, impostare i percorsi dei dischi e avviarli insieme.
Ecco un esempio completo per quattro nodi con due dischi ciascuno:
La sintassi
{1...4}indica a MinIO di connettersi a quattro nodi (minio1 a minio4) con due dischi ciascuno (data1 e data2). Ogni nodo ha mapping di porte unici così puoi accedervi singolarmente: il nodo 1 usa 9001/9091, il nodo 2 usa 9002/9092 e così via.La rete
minio-distributedpermette ai container di raggiungersi per hostname. Tutti i nodi devono usare le stesse credenziali e vedere lo stesso layout dei dischi.Per avviare il cluster, prima crea le directory dei dati e poi esegui il file compose
Esecuzione di MinIO in modalità distribuita
Tutto qui! Ora puoi visitare uno qualsiasi dei seguenti URL per accedere alla web UI:
Ma di nuovo, non costruire tutto questo a meno che non ti serva davvero: la modalità distribuita è per workload di produzione in cui uptime e ridondanza giustificano la complessità extra.
Inoltre, probabilmente vorrai cose come TLS, un endpoint console unico, volumi/dischi esterni per un ambiente di produzione completo.
Problemi comuni nell’esecuzione di MinIO in Docker
La maggior parte dei problemi con MinIO su Docker deriva da volumi, porte o credenziali configurati male.
Ecco i problemi che incontrerai davvero e come risolverli rapidamente.
Il container parte ma la web UI non è accessibile
Esegui
docker pse vedi il container in esecuzione, mahttp://localhost:9001non risponde o va in timeout.Per risolvere, controlla prima che la porta della console sia mappata correttamente:
Dovresti vedere
9001/tcp -> 0.0.0.0:9001. Se non vedi la porta 9001 elencata, hai dimenticato di mapparla nel comando docker run o nel file Compose.Controlla anche i log di MinIO:
Cerca la riga che dice "Console: http://..." — ti indica su quale indirizzo MinIO sta davvero ascoltando. Se vedi una porta diversa da quella prevista, potresti aver impostato male il flag
--console-address.Errori di permessi sui volumi montati
MinIO va in crash all’avvio o nei log vedi errori "permission denied" quando prova a scrivere su
/data.Il processo MinIO gira come un utente specifico nel container e quell’utente deve avere accesso in scrittura alla directory montata. Risolvi con:
Oppure, se sei su Linux, esegui il container con il tuo UID:
Conflitti di porta con altri servizi
All’avvio del container ottieni "bind: address already in use".
Significa che un altro servizio sta già usando la porta 9000 o 9001. Scopri cosa la sta usando:
Poi mappa MinIO su porte host diverse:
Ora accedi all’API su
localhost:9090e alla console sulocalhost:9091.Credenziali che non funzionano come previsto
Hai impostato
MINIO_ROOT_USEReMINIO_ROOT_PASSWORDma non riesci ad accedere o il container non parte.Per risolvere, verifica di aver davvero passato le variabili d’ambiente:
Cerca
MINIO_ROOT_USEReMINIO_ROOT_PASSWORDnell’output. Se mancano, hai dimenticato i flag-eo la sezioneenvironment:nel file Compose.MinIO richiede anche password di almeno 8 caratteri. Se la tua è più corta, il container potrebbe rifiutarla o usarne una di default.
Se hai cambiato le credenziali su un setup esistente, ferma e rimuovi completamente il container, poi riparti da zero:
Vecchi file di credenziali potrebbero persistere nella directory dei dati e causare conflitti.
Best practice per eseguire MinIO con Docker
Segui queste pratiche per evitare errori comuni e mantenere gestibile il tuo setup MinIO.
Usa Docker Compose per la ripetibilità. Un file Compose documenta la tua configurazione esatta: porte, volumi, variabili d’ambiente e comandi. Puoi versionarlo, condividerlo con il team e ricreare setup identici su macchine diverse. Eseguire lunghi comandi
docker rundalla cronologia della shell porta a drift di configurazione ed errori.Configura sempre lo storage persistente. Mappa un volume o un bind mount prima di salvare dati reali. I container sono effimeri: se salti questo passaggio, perderai tutto al riavvio del container. Verifica la configurazione con
docker inspect minioe controlla che il mapping del volume sia corretto.Tieni le credenziali fuori dalla cronologia dei comandi. Non inserire le password direttamente nei comandi
docker runo nei file Compose che mandi su git. Usa file di ambiente (.env) con Docker Compose o passa le credenziali tramite variabili d’ambiente a runtime. Aggiungi subito.enval tuo.gitignore.Usa la modalità single-node solo per lo sviluppo. La modalità distribuita è complessa e lenta da configurare. Non ti servono alta disponibilità o erasure coding sul laptop. Riserva i deployment distribuiti alla produzione, dove il downtime conta davvero.
Monitora i log durante l’avvio. Esegui
docker logs -f minioal primo avvio di MinIO. I log mostrano l’endpoint API, l’URL della console e gli eventuali errori di configurazione. Se qualcosa non va, lo vedrai subito invece di chiederti perché nulla funziona.Segui queste pratiche e il tuo setup MinIO sarà solido dal primo giorno.
Conclusione
Eseguire MinIO con Docker significa avere storage a oggetti compatibile con S3 sulla tua macchina in meno di un minuto.
Per sviluppo, test e progetti su piccola scala, MinIO single-node in Docker ti dà tutto ciò che serve. Ottieni piena compatibilità con le API S3, una console web per la gestione e il controllo totale sui tuoi dati senza dipendere dai servizi cloud o pagare per storage che non usi.
Parti dalle basi: un semplice comando
docker runo un file Docker Compose con volumi persistenti e credenziali sicure (meglio il secondo). Testa il setup, verifica che funzioni e aggiungi complessità solo quando ti serve davvero.La modalità distribuita, l’alta disponibilità e le configurazioni di livello production esistono per un motivo — ma quel motivo non è lo sviluppo locale. Passa a quei setup quando distribuisci in produzione, quando il downtime ti costa denaro o quando stai archiviando dati che non possono andare persi. Fino ad allora, tieni tutto semplice e concentrati a costruire la tua applicazione invece che a gestire l’infrastruttura.
Quando sei pronto per approfondire argomenti Docker più complessi, dai un’occhiata al nostro corso Containerization and Virtualization with Docker and Kubernetes.