MinIO Docker: Handleiding voor het opzetten van S3-compatibele objectopslag
Draai MinIO met Docker voor S3-compatibele objectopslag voor lokale development, inclusief setup, persistente volumes, troubleshooting en wanneer je distributed mode gebruikt.
Heb je objectopslag nodig voor development, maar wil je geen AWS S3 opzetten en ervoor betalen?
MinIO geeft je S3-compatibele opslag die overal draait - op je laptop, een VM of een Kubernetes-cluster. Het is open-source, wat betekent dat het vendor-neutraal is en je geen verrassende rekeningen krijgt aan het eind van de maand. In combinatie met Docker wordt MinIO draaien nóg makkelijker, omdat je in seconden een storage-server kunt starten zonder iets direct op je machine te installeren.
Docker-containers houden MinIO geïsoleerd van je systeem en geven je tegelijk volledige controle over configuratie en gegevenspersistentie. Je kunt S3-API’s lokaal testen, production storage nabootsen of lichte objectopslag draaien voor kleine projecten.
In dit artikel laat ik je zien hoe je MinIO met Docker draait, controleert of alles werkt, en de meest voorkomende configuratie-opties instelt.
Ben je compleet nieuw met Docker, trek er dan een zaterdagmiddag voor uit om de basis te leren - DataCamp’s Introduction to Docker-cursus helpt je op weg.
Vereisten
Je hebt drie dingen nodig om MinIO met Docker te draaien.
Docker geïnstalleerd en draaiend op je machine. Je kunt dit controleren door docker --version in je terminal te draaien. Krijg je een versienummer terug, dan zit je goed.
Basiskennis van Docker-commando’s. Je moet weten hoe je containers start en stopt, logs bekijkt en met Docker-images werkt. Als je wel eens docker run hebt gedraaid of met Docker Compose hebt gewerkt, komt het goed.
Een lokale map voor persistente opslag. MinIO heeft een plek nodig om je data buiten de container op te slaan. Maak een lege map op je hostmachine - iets als ~/minio/data werkt prima.
Dat is alles. De lijst is kort en simpel, maar zorg dat je alle vinkjes kunt zetten voordat je verdergaat.
MinIO draaien met Docker (single-node setup)
Een single-node MinIO-setup draait één instantie van MinIO in een Docker-container en slaat al je data op één plek op.
Deze setup werkt voor development, testen en kleinschalige productie-workloads waarbij je geen hoge beschikbaarheid of gedistribueerde opslag nodig hebt. Je krijgt volledige S3-API-compatibiliteit zonder de complexiteit van meerdere nodes.
MinIO draaien met Docker Run
Met het commando docker run start je MinIO in een nieuwe container, met alles in één regel geconfigureerd.
Dit is het basiscommando:
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"Mogelijk gemaakt door
MinIO draaien met docker run
Laten we bekijken wat elk onderdeel doet.
Poort 9000 is het API-endpoint waar je applicaties verbinden om bestanden te uploaden en te downloaden. Hierheen sturen S3-compatibele clients hun requests.
Poort 9001 host de webconsole waar je buckets beheert, permissies instelt en opslag monitort. Deze gebruik je om te verifiëren dat MinIO correct draait.
De vlag -v ~/minio/data:/data koppelt je lokale map aan de opslaglocatie van de container. Alles wat MinIO opslaat gaat naar ~/minio/data op je hostmachine. Als je de container stopt of verwijdert, blijft je data veilig in deze map staan.
Omgevingsvariabelen stellen je toegangsgegevens in. MINIO_ROOT_USER is je admin-gebruikersnaam en MINIO_ROOT_PASSWORD is het wachtwoord. Met deze gegevens log je in op de webconsole en configureer je API-toegang.
Het argument server /data vertelt MinIO om in servermodus te draaien en /data als opslagmap te gebruiken. De vlag --console-address ":9001" specificeert op welke poort de webconsole luistert.
Er is een alternatief om MinIO te draaien dat ideaal is als je geen fan bent van lange terminalcommando’s over meerdere regels.
Let op: MinIO update zijn Docker Hub- en Quay-images niet meer (sinds oktober 2025). De code in dit artikel werkt nog voor lokale development, maar gebruik voor productie onderhouden alternatieven zoals de MinIO-image van Chainguard (cgr.dev/chainguard/minio:latest).
MinIO draaien met Docker Compose
Met Docker Compose definieer je je MinIO-setup in een YAML-bestand in plaats van lange commando’s te typen.
Zo wordt je configuratie herhaalbaar en versieerbaar. Je kunt het bestand delen met je team, naar git committen en MinIO elke keer opnieuw starten met exact dezelfde instellingen.
Maak een docker-compose.yml-bestand:
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"Mogelijk gemaakt door
De structuur weerspiegelt het docker run-commando, maar ordent alles in benoemde secties. Poorten, omgevingsvariabelen en volumes hebben elk hun eigen blok.
Volumekoppeling werkt hetzelfde - ./minio/data:/data maakt een map in je huidige folder en mount deze naar de container. De ./ betekent: relatief ten opzichte van waar dit docker-compose.yml-bestand staat.
De vlag -d draait de container op de achtergrond. Je terminal wordt niet geblokkeerd door MinIO-logs en de container blijft draaien nadat je de terminal sluit.
Compose is beter voor development omdat je healthchecks, restart policies en meerdere services in hetzelfde bestand kunt toevoegen. Als je later een database of andere services naast MinIO nodig hebt, voeg je simpelweg meer entries toe onder services:.
MinIO benaderen en verifiëren dat het draait
Nu MinIO draait, wil je bevestigen dat het correct is gestart voordat je het gebruikt voor opslag.
Er zijn twee manieren om je setup te verifiëren: de webconsole voor visuele bevestiging en de MinIO-client voor verificatie via de command line.
De MinIO-webconsole gebruiken
Open je browser en ga naar http://localhost:9001.
Je ziet een inlogscherm dat om inloggegevens vraagt:
MinIO web-UI
Je kunt inloggen met de gegevens die je als omgevingsvariabelen hebt opgegeven - admin/password123 in mijn geval.
Na het inloggen kom je op het MinIO-dashboard. De hoofdpagina toont opslaggebruik, aantal buckets en systeemstatus. In de linkerzijbalk kun je buckets aanmaken, gebruikers beheren en metrics bekijken.
Een bucket aanmaken via de MinIO web-UI
Maak een testbucket om te verifiëren dat alles werkt. Klik op "Buckets" in de zijbalk en vervolgens op "Create Bucket". Geef een naam zoals test-bucket en klik op create. Als de bucket in je lijst verschijnt, draait MinIO correct en slaat het data op.
Een bucket aanmaken via de MinIO web-UI
De MinIO-client (mc) gebruiken
De MinIO-client is een commandlinetool waarmee je met MinIO kunt werken, vergelijkbaar met de AWS CLI.
Voer een van deze commando’s uit om hem te installeren:
# macOS
brew install minio/stable/mc
# Linuxwget https://dl.min.io/client/mc/release/linux-amd64/mc
chmod +x mcsudomvmc /usr/local/bin/Mogelijk gemaakt door
En voer nu dit commando uit om de client met je lokale MinIO-instantie te verbinden:
Als je test.txt in de output ziet, is alles correct ingesteld.
Bestanden in een bucket weergeven
Hier is wat snelle troubleshooting als dingen niet werken:
Controleer of de container draait met docker ps. Zie je geen container met de naam minio, dan is hij niet gestart of gecrasht.
Bekijk de logs met docker logs minio. Let op fouten over poorten die al in gebruik zijn of permissieproblemen op de datamap.
Als je niet bij de webconsole kunt, controleer dan of de poorten niet geblokkeerd worden met docker port minio. Je zou zowel 9000 als 9001 correct gemapt moeten zien.
Krijg je permissiefouten op de datamap, voer dan chmod -R 755 ~/minio/data uit om toegangsproblemen te verhelpen.
Persistente opslag en datavolumes
Containers zijn standaard vluchtig - als je een container verwijdert, verdwijnt alles erin.
MinIO slaat objecten, metadata en configuratiebestanden op. Als je persistente opslag niet correct instelt, verlies je al je data zodra je de container herstart of verwijdert.
Lokale volumes gebruiken met Docker
Docker-volumes en bind mounts houden je data veilig buiten de container.
Wanneer je -v ~/minio/data:/data gebruikt of een volume in Docker Compose koppelt, schrijft MinIO alles naar je hostmachine. De container leest en schrijft naar /data, maar die bestanden staan feitelijk in ~/minio/data op je host.
Als je de container stopt, verwijdert of zelfs de image wist - je data blijft in ~/minio/data. Start een nieuwe MinIO-container die naar dezelfde map wijst en al je buckets, objecten en instellingen komen precies terug zoals je ze had.
Als je geen volume koppelt, gebruikt MinIO het interne bestandssysteem van de container. Alles werkt prima tot je de container stopt. Bij het herstarten begint MinIO vers, zonder buckets, objecten of configuratie.
Het compose-voorbeeld dat ik eerder liet zien maakt een map minio/data aan precies waar je compose-bestand staat:
MinIO-datamap
Veelgemaakte opslagfouten
Draaien zonder volume is de meest voorkomende fout.
Je start MinIO, uploadt bestanden, maakt buckets aan en alles lijkt prima. Dan herstart je de container voor een update of configuratiewijziging. Al je data is weg, omdat die in de container stond en niet op je host.
Controleer altijd of je Docker-commando of Compose-bestand een volumekoppeling heeft voordat je echte data in MinIO zet.
Permissieproblemen ontstaan wanneer Docker niet naar je gemounte map kan schrijven.
Het MinIO-proces in de container draait als een specifieke gebruiker. Als die gebruiker geen schrijfrechten heeft op de hostmap, crasht MinIO bij het starten of faalt stilletjes bij het opslaan van objecten.
Je lost dit op door ervoor te zorgen dat je datamap schrijfbaar is:
Kortom: stel je volumes één keer goed in en je hoeft je geen zorgen meer te maken over dataverlies.
Omgevingsvariabelen en basisconfiguratie
MinIO leest zijn configuratie bij het starten uit omgevingsvariabelen.
Dit betekent dat je het gedrag van MinIO kunt aanpassen zonder configbestanden te bewerken of containers te herbouwen. Je stelt deze variabelen in je docker run-commando of Docker Compose-bestand in.
Access keys en credentials
MinIO vereist twee omgevingsvariabelen voor authenticatie: MINIO_ROOT_USER en MINIO_ROOT_PASSWORD.
Deze maken het root-adminaccount aan dat volledige controle heeft over je MinIO-instantie. De rootgebruiker kan buckets maken, andere gebruikers beheren, policies instellen en toegang krijgen tot alle opgeslagen objecten.
Stel ze zo in tijdens docker run:
-e"MINIO_ROOT_USER=admin"\-e"MINIO_ROOT_PASSWORD=your-secure-password"Mogelijk gemaakt door
Of in Docker Compose:
environment:
MINIO_ROOT_USER: admin
MINIO_ROOT_PASSWORD: your-secure-passwordMogelijk gemaakt door
Gebruik geen standaardcredentials in productie. De voorbeelden in dit artikel gebruiken admin en password123 voor de eenvoud, maar dit zijn slechte keuzes voor echte deployments.
Kies een sterk wachtwoord van minimaal 8 tekens. Beter nog: gebruik willekeurig gegenereerde gegevens en bewaar ze in een wachtwoordmanager of secretsbeheersysteem.
Hardcode geen credentials in Docker Compose-bestanden die je in versiebeheer commit. Gebruik in plaats daarvan environment-bestanden:
environment:
MINIO_ROOT_USER: ${MINIO_ROOT_USER}
MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}Mogelijk gemaakt door
Maak vervolgens een .env-bestand met je echte gegevens en voeg het toe aan .gitignore.
Poortconfiguratie en netwerk
MinIO heeft twee poorten nodig om correct te functioneren.
Poort 9000 handelt de S3-API af. Hierheen sturen je applicaties verzoeken om objecten op te slaan en op te halen. Alle S3-compatibele clients verbinden met deze poort.
Poort 9001 serveert de webconsole. Dit is de browserinterface waarmee je MinIO via een GUI beheert.
Nu staat de MinIO-API op http://localhost:9090 en de console op http://localhost:9091. De container gebruikt intern nog steeds 9000 en 9001, maar extern benader je ze via andere poorten.
Met deze commando’s controleer je wat een poort gebruikt voordat je MinIO start:
# Linux/macOSlsof-i :9000
lsof-i :9001
# Windowsnetstat-ano| findstr :9000
netstat-ano| findstr :9001Mogelijk gemaakt door
Controleren wat een poort gebruikt
Als je meerdere MinIO-instanties op dezelfde machine draait, geef elke unieke poortmappings zodat ze elkaar niet in de weg zitten.
MinIO draaien in distributed mode met Docker
Distributed mode draait MinIO over meerdere servers met meerdere schijven voor hoge beschikbaarheid en dataredundantie.
Voor development of testen heb je dit niet nodig. Single-node mode dekt de meeste use-cases prima. Sla deze sectie over, tenzij je een productie-deployment plant die online moet blijven, zelfs als servers uitvallen.
Wanneer distributed MinIO zinvol is
Gebruik distributed mode wanneer je fouttolerantie nodig hebt.
Als één server uitvalt in een distributed setup, blijft MinIO draaien en blijft je data toegankelijk. Het systeem gebruikt erasure coding om objecten over meerdere schijven en servers te verdelen, zodat je schijven of hele nodes kunt verliezen zonder data te verliezen.
Je hebt distributed mode ook nodig voor grootschalige opslag. Als je terabytes of petabytes aan data opslaat, geeft spreiding over meerdere machines je betere prestaties en meer capaciteit dan één server kan bieden.
Lokale development heeft dit allemaal niet nodig. Distributed mode voegt complexiteit toe - je hebt meerdere machines of VM’s nodig, gecoördineerde netwerken en zorgvuldige schijfconfiguratie. Voor het testen van S3-API’s of het draaien van objectopslag op je laptop doet single-node mode alles wat je nodig hebt.
Productieomgevingen gebruiken distributed mode wanneer downtime onacceptabel is en dataverlies catastrofaal zou zijn. Denk aan back-ups, data lakes of applicaties waar gebruikers afhankelijk zijn van constante opslagbeschikbaarheid.
Setup-overzicht op hoog niveau
Distributed MinIO vereist minimaal vier schijven over meerdere nodes.
Elke node draait een MinIO-container en alle nodes moeten dezelfde schijfconfiguratie zien. Je kunt geen nodes met één schijf mengen met nodes met meerdere schijven, of het aantal schijven na setup wijzigen.
Een basis distributed setup ziet er zo uit:
Vier servers (of VM’s) met MinIO geïnstalleerd
Meerdere schijven per server, toegewijd aan MinIO
Netwerkconnectiviteit tussen alle nodes
Identieke schijfpaden op elke node
Je kunt de coördinatie in één Compose-bestand regelen, maar ik waarschuw je - het wordt een lang bestand. Je moet alle nodes definiëren, hun schijfpaden instellen en ze samen starten.
Hier is een volledig voorbeeld voor vier nodes met twee schijven per node:
De syntaxis {1...4} vertelt MinIO om verbinding te maken met vier nodes (minio1 t/m minio4) met elk twee schijven (data1 en data2). Elke node krijgt unieke poortmappings zodat je ze individueel kunt benaderen - node 1 gebruikt 9001/9091, node 2 gebruikt 9002/9092, enzovoort.
Het netwerk minio-distributed laat containers elkaar via hostnamen bereiken. Alle nodes moeten dezelfde credentials gebruiken en dezelfde schijflay-out zien.
Om het cluster te starten, maak je eerst datamappen aan en draai je vervolgens het compose-bestand
Maar nogmaals, bouw dit niet tenzij je het echt nodig hebt - distributed mode is voor productie-workloads waarbij uptime en redundantie de extra complexiteit rechtvaardigen.
Daarnaast wil je waarschijnlijk zaken als TLS, één console-endpoint en externe volumes/schijven voor een volledige productieomgeving.
Veelvoorkomende problemen bij het draaien van MinIO in Docker
De meeste MinIO-Dockerproblemen komen door verkeerd geconfigureerde volumes, poorten of credentials.
Hier zijn de problemen waar je daadwerkelijk tegenaan loopt en hoe je ze snel oplost.
Container start, maar de web-UI is onbereikbaar
Je draait docker ps en ziet de container draaien, maar http://localhost:9001 geeft niets terug of time-out.
Controleer eerst of de consolepoort correct gemapt is:
Zoek naar de regel met "Console: http://..." - die vertelt je op welk adres MinIO daadwerkelijk luistert. Zie je een andere poort dan verwacht, dan staat je --console-address-vlag mogelijk verkeerd.
Permissiefouten op gemounte volumes
MinIO crasht bij het starten of je ziet "permission denied"-fouten in de logs wanneer het naar /data probeert te schrijven.
Het MinIO-proces draait als een specifieke gebruiker in de container en die gebruiker heeft schrijfrechten nodig op je gemounte map. Los dit op met:
Zoek in de output naar MINIO_ROOT_USER en MINIO_ROOT_PASSWORD. Als ze ontbreken, ben je de -e-vlaggen of de sectie environment: in je Compose-bestand vergeten.
MinIO vereist ook wachtwoorden van minimaal 8 tekens. Als je wachtwoord korter is, kan de container het weigeren of een standaard gebruiken.
Heb je credentials gewijzigd in een bestaande setup, stop en verwijder de container volledig en start dan schoon opnieuw:
docker stop minio
dockerrm minio
docker run ... # with new credentialsMogelijk gemaakt door
Oude credentialbestanden kunnen in je datamap blijven staan en conflicten veroorzaken.
Best practices voor MinIO met Docker
Volg deze praktijken om veelgemaakte fouten te vermijden en je MinIO-setup onderhoudbaar te houden.
Gebruik Docker Compose voor herhaalbaarheid. Een Compose-bestand documenteert je exacte configuratie - poorten, volumes, omgevingsvariabelen en commando’s. Je kunt het versiebeheren, delen met je team en identieke setups reproduceren op verschillende machines. Lange docker run-commando’s uit je shellgeschiedenis leiden tot configuratiedrift en fouten.
Configureer altijd persistente opslag. Koppel een volume of bind mount voordat je echte data opslaat. Containers zijn vluchtig - als je deze stap overslaat, verlies je alles bij een herstart. Controleer je setup met docker inspect minio en verifieer dat de volumekoppeling klopt.
Houd credentials uit je commandgeschiedenis. Zet wachtwoorden niet rechtstreeks in docker run-commando’s en commit ze niet in je Compose-bestanden. Gebruik environment-bestanden (.env) met Docker Compose of geef credentials door via omgevingsvariabelen tijdens runtime. Voeg .env meteen toe aan je .gitignore.
Gebruik single-node mode alleen voor development. Distributed mode is complex en traag om op te zetten. Je hebt geen hoge beschikbaarheid of erasure coding nodig op je laptop. Bewaar distributed deployments voor productie, waar downtime echt telt.
Monitor logs tijdens de opstart. Draai docker logs -f minio wanneer je MinIO voor het eerst start. De logs tonen het API-endpoint, de console-URL en eventuele configuratiefouten. Als er iets mis is, zie je het meteen in plaats van je af te vragen waarom niets werkt.
Volg deze praktijken en je MinIO-setup staat vanaf dag één stevig.
Conclusie
MinIO met Docker draaien betekent dat je in minder dan een minuut S3-compatibele objectopslag op je machine hebt draaien.
Voor development, testen en kleinschalige projecten biedt single-node MinIO in Docker alles wat je nodig hebt. Je krijgt volledige S3-API-compatibiliteit, een webconsole voor beheer en volledige controle over je data zonder afhankelijk te zijn van cloudservices of te betalen voor opslag die je niet gebruikt.
Begin met de basis: een eenvoudig docker run-commando of een Docker Compose-bestand met persistente volumes en veilige credentials (de voorkeur voor die laatste). Test je setup, verifieer dat het werkt, en voeg pas complexiteit toe als je het echt nodig hebt.
Distributed mode, hoge beschikbaarheid en productieklare configuraties bestaan met een reden - maar die reden is geen lokale development. Stap over op die setups wanneer je naar productie gaat, wanneer downtime geld kost of wanneer je data opslaat die niet verloren mag gaan. Tot die tijd: houd het simpel en focus op het bouwen van je applicatie in plaats van het managen van infrastructuur.
Senior Data Scientist, gevestigd in Kroatië. Top Tech-schrijver met meer dan 700 gepubliceerde artikelen en meer dan 10 miljoen weergaven. Auteur van het boek Machine Learning Automation with TPOT.
FAQs
Hoe optimaliseer ik de MinIO-prestaties voor uploads met hoge gelijktijdigheid?⌄
Verhoog het aantal gelijktijdige verbindingen dat je MinIO-server aankan door de omgevingsvariabele MINIO_API_REQUESTS_MAX aan te passen. Overweeg voor workloads met hoge gelijktijdigheid ook het gebruik van meerdere schijven in je setup, omdat MinIO de load automatisch over beschikbare schijven verdeelt. Als je in distributed mode draait, zorg dan dat je netwerkbandbreedte tussen nodes het verkeer aankan en gebruik dedicated netwerkinterfaces voor MinIO-communicatie.
Wat zijn best practices voor het opzetten van MinIO met Docker Compose?⌄
Gebruik altijd Docker Compose in plaats van docker run-commando’s voor setups die op productie lijken, omdat dit je configuratie herhaalbaar en versieerbaar maakt. Sla credentials op in een apart .env-bestand en voeg dit toe aan .gitignore om secrets buiten je repository te houden. Koppel persistente volumes aan toegewijde mappen op je host, stel restart policies in op unless-stopped of always en voeg healthcheck-configuraties toe om de containerstatus te monitoren.
Hoe configureer ik MinIO voor veilige toegang met TLS?⌄
Genereer TLS-certificaten en plaats ze in een map op je host, mount die map vervolgens naar /root/.minio/certs in de MinIO-container. MinIO detecteert certificaten op die locatie automatisch en schakelt HTTPS in bij het starten. Je hebt zowel een public.crt-bestand (certificaat) als een private.key-bestand (privésleutel) nodig, en het certificaat moet overeenkomen met de hostnaam of het IP-adres van je MinIO-server.
Wat zijn de belangrijkste verschillen tussen MinIO en andere S3-compatibele alternatieven?⌄
MinIO is volledig open-source en specifiek ontworpen voor high-performance objectopslag, terwijl veel S3-compatibele alternatieven ofwel clouddiensten zijn of een beperkte feature set hebben. MinIO ondersteunt functies zoals gedistribueerde erasure coding, versioning, encryptie en lifecycle policies die overeenkomen met de mogelijkheden van AWS S3. In tegenstelling tot sommige alternatieven draait MinIO overal - op bare metal, VM’s, containers of Kubernetes - en bindt het je niet aan een specifieke cloudprovider.
Hoe kan ik MinIO-back-ups en herstelprocessen automatiseren?⌄
Gebruik de MinIO-client (mc) om scripts te maken die buckets spiegelen naar een andere MinIO-instantie of S3-compatibele opslag met mc mirror source/ destination/. Plan deze scripts met cronjobs of gebruik de ingebouwde bucketreplicatiefunctie van MinIO om data automatisch tussen MinIO-instanties te synchroniseren. Voor restores gebruik je mc mirror in omgekeerde richting om data terug te kopiëren vanaf je backuplocatie, of mc cp met de vlag --recursive om specifieke buckets of objecten te herstellen.
%22%3E%3Cpath%20d%3D%22m-369%200h408v79h-408z%22%20fill%3D%22%237933ff%22%2F%3E%3Cpath%20d%3D%22m-148%200h306v45h-306z%22%20fill%3D%22%23974dff%22%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E)
%22%2F%3E%3C%2FclipPath%3E%3Cg%20clip-path%3D%22url(%23a)%22%3E%3Cpath%20d%3D%22m76%200h484v36h-484z%22%20fill%3D%22%23974dff%22%2F%3E%3Cpath%20d%3D%22m0%200h384v24h-384z%22%20fill%3D%22%2306bdfc%22%20transform%3D%22matrix(1%200%200%20-1%200%2060)%22%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E)
Heb je objectopslag nodig voor development, maar wil je geen AWS S3 opzetten en ervoor betalen?
MinIO geeft je S3-compatibele opslag die overal draait - op je laptop, een VM of een Kubernetes-cluster. Het is open-source, wat betekent dat het vendor-neutraal is en je geen verrassende rekeningen krijgt aan het eind van de maand. In combinatie met Docker wordt MinIO draaien nóg makkelijker, omdat je in seconden een storage-server kunt starten zonder iets direct op je machine te installeren.
Docker-containers houden MinIO geïsoleerd van je systeem en geven je tegelijk volledige controle over configuratie en gegevenspersistentie. Je kunt S3-API’s lokaal testen, production storage nabootsen of lichte objectopslag draaien voor kleine projecten.
In dit artikel laat ik je zien hoe je MinIO met Docker draait, controleert of alles werkt, en de meest voorkomende configuratie-opties instelt.
Ben je compleet nieuw met Docker, trek er dan een zaterdagmiddag voor uit om de basis te leren - DataCamp’s Introduction to Docker-cursus helpt je op weg.
Vereisten
Je hebt drie dingen nodig om MinIO met Docker te draaien.
Docker geïnstalleerd en draaiend op je machine. Je kunt dit controleren door
docker --versionin je terminal te draaien. Krijg je een versienummer terug, dan zit je goed.Basiskennis van Docker-commando’s. Je moet weten hoe je containers start en stopt, logs bekijkt en met Docker-images werkt. Als je wel eens
docker runhebt gedraaid of met Docker Compose hebt gewerkt, komt het goed.Een lokale map voor persistente opslag. MinIO heeft een plek nodig om je data buiten de container op te slaan. Maak een lege map op je hostmachine - iets als
~/minio/datawerkt prima.Dat is alles. De lijst is kort en simpel, maar zorg dat je alle vinkjes kunt zetten voordat je verdergaat.
MinIO draaien met Docker (single-node setup)
Een single-node MinIO-setup draait één instantie van MinIO in een Docker-container en slaat al je data op één plek op.
Deze setup werkt voor development, testen en kleinschalige productie-workloads waarbij je geen hoge beschikbaarheid of gedistribueerde opslag nodig hebt. Je krijgt volledige S3-API-compatibiliteit zonder de complexiteit van meerdere nodes.
MinIO draaien met Docker Run
Met het commando
docker runstart je MinIO in een nieuwe container, met alles in één regel geconfigureerd.Dit is het basiscommando:
MinIO draaien met docker run
Laten we bekijken wat elk onderdeel doet.
Poort 9000 is het API-endpoint waar je applicaties verbinden om bestanden te uploaden en te downloaden. Hierheen sturen S3-compatibele clients hun requests.
Poort 9001 host de webconsole waar je buckets beheert, permissies instelt en opslag monitort. Deze gebruik je om te verifiëren dat MinIO correct draait.
De vlag
-v ~/minio/data:/datakoppelt je lokale map aan de opslaglocatie van de container. Alles wat MinIO opslaat gaat naar~/minio/dataop je hostmachine. Als je de container stopt of verwijdert, blijft je data veilig in deze map staan.Omgevingsvariabelen stellen je toegangsgegevens in.
MINIO_ROOT_USERis je admin-gebruikersnaam enMINIO_ROOT_PASSWORDis het wachtwoord. Met deze gegevens log je in op de webconsole en configureer je API-toegang.Het argument
server /datavertelt MinIO om in servermodus te draaien en/dataals opslagmap te gebruiken. De vlag--console-address ":9001"specificeert op welke poort de webconsole luistert.Er is een alternatief om MinIO te draaien dat ideaal is als je geen fan bent van lange terminalcommando’s over meerdere regels.
Let op: MinIO update zijn Docker Hub- en Quay-images niet meer (sinds oktober 2025). De code in dit artikel werkt nog voor lokale development, maar gebruik voor productie onderhouden alternatieven zoals de MinIO-image van Chainguard (cgr.dev/chainguard/minio:latest).
MinIO draaien met Docker Compose
Met Docker Compose definieer je je MinIO-setup in een YAML-bestand in plaats van lange commando’s te typen.
Zo wordt je configuratie herhaalbaar en versieerbaar. Je kunt het bestand delen met je team, naar git committen en MinIO elke keer opnieuw starten met exact dezelfde instellingen.
Maak een
docker-compose.yml-bestand:De structuur weerspiegelt het
docker run-commando, maar ordent alles in benoemde secties. Poorten, omgevingsvariabelen en volumes hebben elk hun eigen blok.Volumekoppeling werkt hetzelfde -
./minio/data:/datamaakt een map in je huidige folder en mount deze naar de container. De./betekent: relatief ten opzichte van waar ditdocker-compose.yml-bestand staat.Je kunt MinIO nu starten met:
MinIO draaien met docker compose
De vlag
-ddraait de container op de achtergrond. Je terminal wordt niet geblokkeerd door MinIO-logs en de container blijft draaien nadat je de terminal sluit.Stoppen doe je met:
Compose is beter voor development omdat je healthchecks, restart policies en meerdere services in hetzelfde bestand kunt toevoegen. Als je later een database of andere services naast MinIO nodig hebt, voeg je simpelweg meer entries toe onder
services:.MinIO benaderen en verifiëren dat het draait
Nu MinIO draait, wil je bevestigen dat het correct is gestart voordat je het gebruikt voor opslag.
Er zijn twee manieren om je setup te verifiëren: de webconsole voor visuele bevestiging en de MinIO-client voor verificatie via de command line.
De MinIO-webconsole gebruiken
Open je browser en ga naar
http://localhost:9001.Je ziet een inlogscherm dat om inloggegevens vraagt:
MinIO web-UI
Je kunt inloggen met de gegevens die je als omgevingsvariabelen hebt opgegeven -
admin/password123in mijn geval.Na het inloggen kom je op het MinIO-dashboard. De hoofdpagina toont opslaggebruik, aantal buckets en systeemstatus. In de linkerzijbalk kun je buckets aanmaken, gebruikers beheren en metrics bekijken.
Een bucket aanmaken via de MinIO web-UI
Maak een testbucket om te verifiëren dat alles werkt. Klik op "Buckets" in de zijbalk en vervolgens op "Create Bucket". Geef een naam zoals
test-bucketen klik op create. Als de bucket in je lijst verschijnt, draait MinIO correct en slaat het data op.Een bucket aanmaken via de MinIO web-UI
De MinIO-client (mc) gebruiken
De MinIO-client is een commandlinetool waarmee je met MinIO kunt werken, vergelijkbaar met de AWS CLI.
Voer een van deze commando’s uit om hem te installeren:
En voer nu dit commando uit om de client met je lokale MinIO-instantie te verbinden:
Dit maakt een alias
localaan die naar je MinIO-server wijst. Je kunt er nu commando’s tegenaan draaien.Lijst je buckets op:
Buckets weergeven
Als je eerder de testbucket hebt aangemaakt, zie je die in de output. Als het commando leeg terugkomt of je buckets toont, werkt MinIO.
Je kunt nu een testbestand uploaden naar de bucket:
En daarna verifiëren dat het er staat:
Als je
test.txtin de output ziet, is alles correct ingesteld.Bestanden in een bucket weergeven
Hier is wat snelle troubleshooting als dingen niet werken:
Controleer of de container draait met
docker ps. Zie je geen container met de naamminio, dan is hij niet gestart of gecrasht.Bekijk de logs met
docker logs minio. Let op fouten over poorten die al in gebruik zijn of permissieproblemen op de datamap.Als je niet bij de webconsole kunt, controleer dan of de poorten niet geblokkeerd worden met
docker port minio. Je zou zowel 9000 als 9001 correct gemapt moeten zien.Krijg je permissiefouten op de datamap, voer dan
chmod -R 755 ~/minio/datauit om toegangsproblemen te verhelpen.Persistente opslag en datavolumes
Containers zijn standaard vluchtig - als je een container verwijdert, verdwijnt alles erin.
MinIO slaat objecten, metadata en configuratiebestanden op. Als je persistente opslag niet correct instelt, verlies je al je data zodra je de container herstart of verwijdert.
Lokale volumes gebruiken met Docker
Docker-volumes en bind mounts houden je data veilig buiten de container.
Wanneer je
-v ~/minio/data:/datagebruikt of een volume in Docker Compose koppelt, schrijft MinIO alles naar je hostmachine. De container leest en schrijft naar/data, maar die bestanden staan feitelijk in~/minio/dataop je host.Als je de container stopt, verwijdert of zelfs de image wist - je data blijft in
~/minio/data. Start een nieuwe MinIO-container die naar dezelfde map wijst en al je buckets, objecten en instellingen komen precies terug zoals je ze had.Als je geen volume koppelt, gebruikt MinIO het interne bestandssysteem van de container. Alles werkt prima tot je de container stopt. Bij het herstarten begint MinIO vers, zonder buckets, objecten of configuratie.
Het compose-voorbeeld dat ik eerder liet zien maakt een map
minio/dataaan precies waar je compose-bestand staat:MinIO-datamap
Veelgemaakte opslagfouten
Draaien zonder volume is de meest voorkomende fout.
Je start MinIO, uploadt bestanden, maakt buckets aan en alles lijkt prima. Dan herstart je de container voor een update of configuratiewijziging. Al je data is weg, omdat die in de container stond en niet op je host.
Controleer altijd of je Docker-commando of Compose-bestand een volumekoppeling heeft voordat je echte data in MinIO zet.
Permissieproblemen ontstaan wanneer Docker niet naar je gemounte map kan schrijven.
Het MinIO-proces in de container draait als een specifieke gebruiker. Als die gebruiker geen schrijfrechten heeft op de hostmap, crasht MinIO bij het starten of faalt stilletjes bij het opslaan van objecten.
Je lost dit op door ervoor te zorgen dat je datamap schrijfbaar is:
Of draai de container met een gebruiker die overeenkomt met je hostgebruiker:
Kortom: stel je volumes één keer goed in en je hoeft je geen zorgen meer te maken over dataverlies.
Omgevingsvariabelen en basisconfiguratie
MinIO leest zijn configuratie bij het starten uit omgevingsvariabelen.
Dit betekent dat je het gedrag van MinIO kunt aanpassen zonder configbestanden te bewerken of containers te herbouwen. Je stelt deze variabelen in je
docker run-commando of Docker Compose-bestand in.Access keys en credentials
MinIO vereist twee omgevingsvariabelen voor authenticatie:
MINIO_ROOT_USERenMINIO_ROOT_PASSWORD.Deze maken het root-adminaccount aan dat volledige controle heeft over je MinIO-instantie. De rootgebruiker kan buckets maken, andere gebruikers beheren, policies instellen en toegang krijgen tot alle opgeslagen objecten.
Stel ze zo in tijdens
docker run:Of in Docker Compose:
Gebruik geen standaardcredentials in productie. De voorbeelden in dit artikel gebruiken
adminenpassword123voor de eenvoud, maar dit zijn slechte keuzes voor echte deployments.Kies een sterk wachtwoord van minimaal 8 tekens. Beter nog: gebruik willekeurig gegenereerde gegevens en bewaar ze in een wachtwoordmanager of secretsbeheersysteem.
Hardcode geen credentials in Docker Compose-bestanden die je in versiebeheer commit. Gebruik in plaats daarvan environment-bestanden:
Maak vervolgens een
.env-bestand met je echte gegevens en voeg het toe aan.gitignore.Poortconfiguratie en netwerk
MinIO heeft twee poorten nodig om correct te functioneren.
Map deze poorten in je Docker-commando:
Poortconflicten ontstaan wanneer een andere service 9000 of 9001 al gebruikt op je host.
Je ziet bij het starten een fout als "bind: address already in use". Los dit op door naar andere hostpoorten te mappen:
Nu staat de MinIO-API op
http://localhost:9090en de console ophttp://localhost:9091. De container gebruikt intern nog steeds 9000 en 9001, maar extern benader je ze via andere poorten.Met deze commando’s controleer je wat een poort gebruikt voordat je MinIO start:
Controleren wat een poort gebruikt
Als je meerdere MinIO-instanties op dezelfde machine draait, geef elke unieke poortmappings zodat ze elkaar niet in de weg zitten.
MinIO draaien in distributed mode met Docker
Distributed mode draait MinIO over meerdere servers met meerdere schijven voor hoge beschikbaarheid en dataredundantie.
Voor development of testen heb je dit niet nodig. Single-node mode dekt de meeste use-cases prima. Sla deze sectie over, tenzij je een productie-deployment plant die online moet blijven, zelfs als servers uitvallen.
Wanneer distributed MinIO zinvol is
Gebruik distributed mode wanneer je fouttolerantie nodig hebt.
Als één server uitvalt in een distributed setup, blijft MinIO draaien en blijft je data toegankelijk. Het systeem gebruikt erasure coding om objecten over meerdere schijven en servers te verdelen, zodat je schijven of hele nodes kunt verliezen zonder data te verliezen.
Je hebt distributed mode ook nodig voor grootschalige opslag. Als je terabytes of petabytes aan data opslaat, geeft spreiding over meerdere machines je betere prestaties en meer capaciteit dan één server kan bieden.
Lokale development heeft dit allemaal niet nodig. Distributed mode voegt complexiteit toe - je hebt meerdere machines of VM’s nodig, gecoördineerde netwerken en zorgvuldige schijfconfiguratie. Voor het testen van S3-API’s of het draaien van objectopslag op je laptop doet single-node mode alles wat je nodig hebt.
Productieomgevingen gebruiken distributed mode wanneer downtime onacceptabel is en dataverlies catastrofaal zou zijn. Denk aan back-ups, data lakes of applicaties waar gebruikers afhankelijk zijn van constante opslagbeschikbaarheid.
Setup-overzicht op hoog niveau
Distributed MinIO vereist minimaal vier schijven over meerdere nodes.
Elke node draait een MinIO-container en alle nodes moeten dezelfde schijfconfiguratie zien. Je kunt geen nodes met één schijf mengen met nodes met meerdere schijven, of het aantal schijven na setup wijzigen.
Een basis distributed setup ziet er zo uit:
Je kunt de coördinatie in één Compose-bestand regelen, maar ik waarschuw je - het wordt een lang bestand. Je moet alle nodes definiëren, hun schijfpaden instellen en ze samen starten.
Hier is een volledig voorbeeld voor vier nodes met twee schijven per node:
De syntaxis
{1...4}vertelt MinIO om verbinding te maken met vier nodes (minio1 t/m minio4) met elk twee schijven (data1 en data2). Elke node krijgt unieke poortmappings zodat je ze individueel kunt benaderen - node 1 gebruikt 9001/9091, node 2 gebruikt 9002/9092, enzovoort.Het netwerk
minio-distributedlaat containers elkaar via hostnamen bereiken. Alle nodes moeten dezelfde credentials gebruiken en dezelfde schijflay-out zien.Om het cluster te starten, maak je eerst datamappen aan en draai je vervolgens het compose-bestand
MinIO in distributed mode draaien
Dat is het! Je kunt nu een van de volgende URL’s bezoeken om de web-UI te openen:
Maar nogmaals, bouw dit niet tenzij je het echt nodig hebt - distributed mode is voor productie-workloads waarbij uptime en redundantie de extra complexiteit rechtvaardigen.
Daarnaast wil je waarschijnlijk zaken als TLS, één console-endpoint en externe volumes/schijven voor een volledige productieomgeving.
Veelvoorkomende problemen bij het draaien van MinIO in Docker
De meeste MinIO-Dockerproblemen komen door verkeerd geconfigureerde volumes, poorten of credentials.
Hier zijn de problemen waar je daadwerkelijk tegenaan loopt en hoe je ze snel oplost.
Container start, maar de web-UI is onbereikbaar
Je draait
docker psen ziet de container draaien, maarhttp://localhost:9001geeft niets terug of time-out.Controleer eerst of de consolepoort correct gemapt is:
Je zou
9001/tcp -> 0.0.0.0:9001moeten zien. Zie je poort 9001 niet, dan ben je vergeten hem te mappen in je docker run-commando of Compose-bestand.Controleer ook de MinIO-logs:
Zoek naar de regel met "Console: http://..." - die vertelt je op welk adres MinIO daadwerkelijk luistert. Zie je een andere poort dan verwacht, dan staat je
--console-address-vlag mogelijk verkeerd.Permissiefouten op gemounte volumes
MinIO crasht bij het starten of je ziet "permission denied"-fouten in de logs wanneer het naar
/dataprobeert te schrijven.Het MinIO-proces draait als een specifieke gebruiker in de container en die gebruiker heeft schrijfrechten nodig op je gemounte map. Los dit op met:
Of, als je Linux gebruikt, draai de container met jouw user-ID:
Poortconflicten met andere services
Je krijgt "bind: address already in use" bij het starten van de container.
Dit betekent dat een andere service poort 9000 of 9001 al gebruikt. Zoek uit wat ‘m gebruikt:
En map MinIO vervolgens naar andere hostpoorten:
Benader de API nu op
localhost:9090en de console oplocalhost:9091.Credentials werken niet zoals verwacht
Je stelt
MINIO_ROOT_USERenMINIO_ROOT_PASSWORDin, maar je kunt niet inloggen of de container start niet.Controleer of je de omgevingsvariabelen echt hebt meegegeven:
Zoek in de output naar
MINIO_ROOT_USERenMINIO_ROOT_PASSWORD. Als ze ontbreken, ben je de-e-vlaggen of de sectieenvironment:in je Compose-bestand vergeten.MinIO vereist ook wachtwoorden van minimaal 8 tekens. Als je wachtwoord korter is, kan de container het weigeren of een standaard gebruiken.
Heb je credentials gewijzigd in een bestaande setup, stop en verwijder de container volledig en start dan schoon opnieuw:
Oude credentialbestanden kunnen in je datamap blijven staan en conflicten veroorzaken.
Best practices voor MinIO met Docker
Volg deze praktijken om veelgemaakte fouten te vermijden en je MinIO-setup onderhoudbaar te houden.
Gebruik Docker Compose voor herhaalbaarheid. Een Compose-bestand documenteert je exacte configuratie - poorten, volumes, omgevingsvariabelen en commando’s. Je kunt het versiebeheren, delen met je team en identieke setups reproduceren op verschillende machines. Lange
docker run-commando’s uit je shellgeschiedenis leiden tot configuratiedrift en fouten.Configureer altijd persistente opslag. Koppel een volume of bind mount voordat je echte data opslaat. Containers zijn vluchtig - als je deze stap overslaat, verlies je alles bij een herstart. Controleer je setup met
docker inspect minioen verifieer dat de volumekoppeling klopt.Houd credentials uit je commandgeschiedenis. Zet wachtwoorden niet rechtstreeks in
docker run-commando’s en commit ze niet in je Compose-bestanden. Gebruik environment-bestanden (.env) met Docker Compose of geef credentials door via omgevingsvariabelen tijdens runtime. Voeg.envmeteen toe aan je.gitignore.Gebruik single-node mode alleen voor development. Distributed mode is complex en traag om op te zetten. Je hebt geen hoge beschikbaarheid of erasure coding nodig op je laptop. Bewaar distributed deployments voor productie, waar downtime echt telt.
Monitor logs tijdens de opstart. Draai
docker logs -f miniowanneer je MinIO voor het eerst start. De logs tonen het API-endpoint, de console-URL en eventuele configuratiefouten. Als er iets mis is, zie je het meteen in plaats van je af te vragen waarom niets werkt.Volg deze praktijken en je MinIO-setup staat vanaf dag één stevig.
Conclusie
MinIO met Docker draaien betekent dat je in minder dan een minuut S3-compatibele objectopslag op je machine hebt draaien.
Voor development, testen en kleinschalige projecten biedt single-node MinIO in Docker alles wat je nodig hebt. Je krijgt volledige S3-API-compatibiliteit, een webconsole voor beheer en volledige controle over je data zonder afhankelijk te zijn van cloudservices of te betalen voor opslag die je niet gebruikt.
Begin met de basis: een eenvoudig
docker run-commando of een Docker Compose-bestand met persistente volumes en veilige credentials (de voorkeur voor die laatste). Test je setup, verifieer dat het werkt, en voeg pas complexiteit toe als je het echt nodig hebt.Distributed mode, hoge beschikbaarheid en productieklare configuraties bestaan met een reden - maar die reden is geen lokale development. Stap over op die setups wanneer je naar productie gaat, wanneer downtime geld kost of wanneer je data opslaat die niet verloren mag gaan. Tot die tijd: houd het simpel en focus op het bouwen van je applicatie in plaats van het managen van infrastructuur.
Klaar om dieper in complexere Docker-onderwerpen te duiken, bekijk dan onze Containerization and Virtualization with Docker and Kubernetes-cursus.