backend/docs/docker-minio-local-dev.md

Docker MinIO Local Development

Local object storage is provided by MinIO in docker-compose.yml.

Port policy

• MinIO S3 API (9000) is internal-only (not published on host).
• MinIO admin UI is exposed on 8774.

Services

• minio: object storage
• minio-init: one-shot bucket bootstrap using mc
• api / api-dev: use MinIO via internal DNS endpoint minio:9000

Environment variables

• S3_ENDPOINT (default minio:9000)
• S3_BUCKET (default momswap-assets)
• S3_REGION (default us-east-1)
• S3_ACCESS_KEY (default momswap)
• S3_SECRET_KEY (default momswap-secret)
• S3_USE_PATH_STYLE (default true)
• S3_USE_TLS (default false)

Start stack

./bin/gen-server-keys.sh
docker compose up --build -d

Verify storage setup

1. Confirm only MinIO UI is published:

   docker compose ps
   

2. Open MinIO admin console:
   • http://localhost:8774
3. Confirm bucket exists (momswap-assets by default).
4. Use API flow:
   • create asset and get signed upload URL
   • upload file with PUT
   • request /v1/assets/{id}/download

Quick verification script

Use this as a smoke-check after startup:

# 1) check API and MinIO UI reachability
curl -fsS http://localhost:8122/healthz
curl -I http://localhost:8774

# 2) ensure MinIO S3 API is not exposed on host
if curl -fsS http://localhost:9000/minio/health/live >/dev/null 2>&1; then
  echo "Unexpected: MinIO S3 API is exposed on host"
else
  echo "OK: MinIO S3 API is internal-only"
fi

Troubleshooting

• If api fails with storage config errors, verify S3_* variables in compose environment.
• If bucket bootstrap fails, inspect:
  • docker compose logs minio
  • docker compose logs minio-init
• If signed URLs are generated but upload fails, check:
  • object key path style (S3_USE_PATH_STYLE=true for MinIO)
  • MinIO credentials (S3_ACCESS_KEY, S3_SECRET_KEY)