Docker로 MinIO 생성하기

MinIO 사용시 도커를 사용하는 이유

MinIO는 S3 호환 오브젝트 스토리지로, 이미지·파일·백업 같은 대용량 데이터를 저장할 때 사용함. AWS S3를 쓰기 전에 로컬에서 똑같이 테스트하거나, 자체 서버에 S3 대체용으로 올릴 때 유용함.

• 컴퓨터에 직접 설치하지 않아도 되서 편하게 만들 수 있고, OS 오염이 없음
• 팀 또는 프로젝트마다 버전/설정을 격리할 수 있음
• 설정을 파일(docker-compose.yml)로 남기면 누구나 똑같이 재현 가능

생성 방법은 두가지

• 방법 1 - docker run : 명령 한 줄로 빠르게 생성 가능. 단발성/실험용.
• 방법 2 - docker compose : 설정을 파일로 관리. 실제 프로젝트에서는 이 방식 사용을 권장.

docker-compose.yml 작성

프로젝트 루트에 docker-compose.yml 작성

services:
  minio:
    image: minio/minio:latest
    container_name: my-minio
    restart: unless-stopped
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin123
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - minio-data:/data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 10s
      timeout: 5s
      retries: 5
volumes:
  minio-data:

1. 서비스 정의(services)

도커 컴포즈로 실행할 컨테이너(서비스)들을 정의하는 최상위 블록

• minio: : 이 컨테이너의 서비스 이름. 도커 네트워크 내부의 컨테이너들끼리 서로를 부를 때 쓰는 주소 겸 역할명
• image: minio/minio:latest : 도커 허브(Docker Hub)에서 가져올 이미지를 지정. 공식 MinIO 이미지를 사용하겠다는 의미
• container_name: my-minio : 실행될 컨테이너의 고유한 이름
• restart: unless-stopped : 컨테이너 재시작 정책. 사용자가 직접 멈추지(docker stop) 않는 이상, 에러로 인해 종료되거나 컴퓨터(서버)가 재부팅될 때 컨테이너를 자동으로 다시 실행함.
  • no : 기본값, 재시작 안함
  • always : 무조건 다시 시작
  • on-failure : 비정상 종료시만 재시작
• command: server /data --console-address ":9001" : MinIO를 서버 모드로 실행하는 명령. PostgreSQL과 달리 MinIO는 실행 명령을 직접 지정해줘야 함.
  • server /data : /data 경로를 오브젝트 저장소로 사용하겠다는 의미
  • --console-address ":9001" : 웹 관리 콘솔을 9001 포트로 열어줌

2. 환경 변수(environment)

컨테이너 내부에서 MinIO가 처음 실행될 때 필요한 설정값들 지정

• MINIO_ROOT_USER: minioadmin : MinIO의 최고 관리자(root) 계정 이름을 minioadmin으로 생성함.
• MINIO_ROOT_PASSWORD: minioadmin123 : 해당 관리자 계정의 비밀번호를 설정함. MinIO는 비밀번호를 최소 8자 이상으로 요구하므로 주의.

3. 포트 연결(ports)

호스트(현재 내 컴퓨터 또는 서버)와 컨테이너 간의 네트워크 포트를 연결. PostgreSQL은 포트가 1개였지만, MinIO는 API용과 콘솔용 2개를 연결함.

• - "9000:9000" : [호스트 포트]:[컨테이너 포트] 형태. S3 호환 API 포트. 애플리케이션이나 mc 클라이언트가 실제로 데이터를 주고받는 통로.
• - "9001:9001" : 웹 관리 콘솔 포트. 브라우저로 접속해서 GUI로 버킷과 파일을 관리하는 화면.

4. 데이터 저장소(volumes)

도커 컨테이너는 삭제되면 내부 데이터가 모두 삭제됨. 이를 방지하고 데이터를 영구 보존하기 위해 사용

• - minio-data:/data : 아래 정의되는 minio-data라는 도커 관리 볼륨을, 컨테이너 내부에서 오브젝트가 실제로 저장되는 경로(/data)와 연결함. 이렇게 하면 컨테이너를 지웠다 다시 만들어도 데이터가 그대로 유지됨.

5. 볼륨 선언 (최하단 volumes)

• minio-data: : 위 서비스 블록에서 사용한 minio-data라는 이름의 '네임드 볼륨(Named Volume)'을 도커가 생성하고 관리하도록 선언하는 최상위 항목

 

도커 생성하기

docker-compose.yml 파일을 작성하고, 해당 폴더에서 아래와 같이 도커를 생성하고 시작합니다.

$ docker compose up -d      # 생성 + 시작
$ docker compose ps         # 상태 확인

 

MinIO 접근하기

MinIO는 psql 같은 전용 셸 대신, 웹 콘솔과 mc(MinIO Client) 두 가지 방법으로 접근함.

1. 웹 콘솔로 접근

브라우저에서 http://localhost:9001 로 접속한 뒤, 위에서 설정한 MINIO_ROOT_USER / MINIO_ROOT_PASSWORD 로 로그인. 버킷(Bucket) 생성, 파일 업로드·다운로드 등을 마우스로 관리할 수 있음. 가장 간단한 방법.

2. mc 클라이언트로 접근

mc는 MinIO를 명령줄에서 다루는 전용 클라이언트. 별도 컨테이너의 셸로 들어가서 사용함.

$ docker run --rm -it --entrypoint /bin/sh minio/mc

/ # mc alias set local http://host.docker.internal:9000 minioadmin minioadmin123
/ # mc ls local                # 버킷 목록 확인
/ # mc mb local/mybucket       # mybucket 이라는 버킷 생성

• --entrypoint /bin/sh : minio/mc 이미지는 기본 실행이 mc 명령이라, 셸로 먼저 들어가기 위해 진입점을 sh로 바꿔줌.
• mc alias set local ... : local이라는 별칭으로 MinIO 서버 주소와 접속 정보(계정/비번)를 등록. 이후 명령에서 local로 서버를 가리킬 수 있음.
• host.docker.internal : 컨테이너 내부에서 호스트(내 컴퓨터)를 가리키는 주소 (Docker Desktop 기준).

접속에 사용한 도커 태그 설명

• "-i (--interactive)" 태그 : 표준 입력(STDIN)을 열어둠. 이 옵션이 있어야 사용자가 키보드로 치는 명령어가 컨테이너 내부의 셸로 전달될 수 있음.
• "-t (--tty)" 태그 : 가상 터미널(pseudo-TTY)을 할당. 화면에 출력되는 텍스트의 줄바꿈이나 포맷팅을 예쁘게 해주고, 방향키(이전 명령어 불러오기)나 Ctrl + C 같은 키보드 단축키가 터미널에서 정상적으로 작동하도록 만들어 줌.
• "--rm" 태그 : 명령이 끝나면(셸에서 나오면) 컨테이너를 자동으로 삭제. mc는 일회성으로 쓰는 경우가 많아 매번 지워줌.
• 요약 > "-it" 태그는 "내 컴퓨터의 터미널을 컨테이너 내부의 셸과 연결해서, 직접 키보드로 입력하며 대화형으로 MinIO를 다루겠다"는 의미.

상태 및 로그, 시작/종료

$ docker compose ps                 # 또는: docker ps
$ docker compose logs -f minio      # 실시간 로그 (Ctrl+C로 보기 종료)
$ docker compose stop               # 끄기(데이터·컨테이너 유지)
$ docker compose start              # 다시 켜기
$ docker compose restart minio      # 재시작

 

데이터 초기화

오브젝트 데이터는 볼륨에 저장되므로, 컨테이너를 지워도 데이터가 남음. 아래 세가지를 구분해서 사용해야 함.

명령	컨테이너	데이터(볼륨)
docker compose stop	멈춤(유지)	유지
docker compose down	제거	유지
docker compose down -v	제거	삭제(초기화)