Running MinIO locally with Docker Compose

When developing applications that interact with object storage like AWS S3, it’s useful to have a local setup that mimics the real service. MinIO is an open-source S3-compatible object storage server that fits perfectly for this purpose.

The official Docker Compose configuration provided by MinIO is quite comprehensive, but it’s unnecessarily complex for simple local development scenarios. It includes multiple services, networking setups, and configurations that might be overkill if you just need a basic MinIO instance with a few buckets.

Bitnami’s MinIO Docker image (bitnami/minio) has undergone changes and is no longer maintained, so we can’t use it either. Though it was a popular choice, the official MinIO image from quay.io/minio/minio is now the recommended way to run MinIO in Docker locally.

So, let’s create our own simple Docker Compose file that’s easy to use for local development.

The configuration consists of two services: the MinIO server itself and a separate service for creating buckets. Bitnami image could do it in a single service, but we will keep it simple here.

MinIO comes with a powerful CLI tool called mc (MinIO Client) that allows you to manage buckets, users, policies, and more. We’ll leverage this to create buckets automatically when the containers start.

To create buckets on startup, we use a separate container that runs mc commands. This container depends on the MinIO service and runs once to set up the initial buckets. (mc is also available in quay.io registry.

Here’s the complete Docker Compose configuration that I recommend for local MinIO development:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

services:
  minio:
    image: quay.io/minio/minio:latest
    ports:
      - "9000:9000"
      - "9001:9001"
    command: [ "server", "--console-address", ":9001", "/data" ]
    volumes:
      - data-minio:/data
    environment:
      MINIO_ROOT_USER: changemeuser
      MINIO_ROOT_PASSWORD: changemepass

  minio-buckets:
    image: quay.io/minio/mc:latest
    depends_on:
      - minio
    restart: on-failure
    entrypoint: >
      /bin/sh -c "
      /usr/bin/mc alias set dockerminio http://minio:9000 changemeuser changemepass;
      /usr/bin/mc mb dockerminio/yourbucketname;
      exit 0;
      "

volumes:
    data-minio:

To run this setup, save the configuration to a compose.yml file and execute docker-compose up. The MinIO web console will be available at http://localhost:9001, and the API at http://localhost:9000. Use the credentials changemeuser and changemepass to log in (remember to change them for production use).

This simple setup gives you a fully functional MinIO instance with automatic bucket creation, perfect for local development.