MinIO Setup Guide¶

Overview¶

MinIO is a high-performance, S3-compatible object storage service that's self-hosted and free. It's configured as part of the shared infrastructure and can be used by the file-service instead of AWS S3.

Architecture¶

Service: po-minio (shared infrastructure)
API Port: 9000 (internal)
Console Port: 9001 (web UI)
Storage: Persistent volume po-minio-data
Networks: po-shared-network, traefik-public

Configuration¶

Environment Variables¶

MinIO is configured via .env.shared:

MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=REPLACE_ME_STRONG_PASSWORD

Buckets¶

Buckets are automatically created on first startup: - po-files-qual - Qualification environment files - po-files-prod - Production environment files

Access Points¶

Internal (Service-to-Service)¶

API Endpoint: http://minio:9000
Console: http://minio:9001

External (via Traefik)¶

API: https://s3.portugalodyssey.pt (requires auth)
Console: https://s3-console.portugalodyssey.pt (requires auth)

File Service Configuration¶

Qualification Environment¶

The file-service is configured to use MinIO in qualification.yml:

environment:
  - FILE_PROVIDER=minio
  - S3_ENDPOINT=http://minio:9000
  - S3_ACCESS_KEY=${MINIO_ROOT_USER_QUAL}
  - S3_SECRET_KEY=${MINIO_ROOT_PASSWORD_QUAL}
  - S3_REGION=us-east-1
  - S3_BUCKET=po-files-qual
  - S3_PUBLIC_URL=http://minio:9000/po-files-qual

Environment Variables (.env.qualification)¶

MINIO_ROOT_USER_QUAL=minioadmin
MINIO_ROOT_PASSWORD_QUAL=REPLACE_ME_STRONG_PASSWORD_MATCH_SHARED

Initial Setup¶

1. Start Shared Infrastructure¶

cd /opt/po-platform
docker compose -f infrastructure/compose/shared.yml --env-file .env.shared up -d

2. Verify MinIO is Running¶

docker ps | grep minio
docker logs po-minio

3. Check Bucket Initialization¶

docker logs po-minio-init

You should see:

Creating buckets...
Bucket po-files-qual already exists
Bucket po-files-prod already exists
Setting bucket policies...
MinIO initialization complete!

4. Access MinIO Console¶

Navigate to https://s3-console.portugalodyssey.pt
Login with:
Username: minioadmin (or value from MINIO_ROOT_USER)
Password: Value from MINIO_ROOT_PASSWORD

Manual Bucket Management¶

Using MinIO Client (mc)¶

# Install mc (if not already installed)
docker run --rm -it --network po-shared-network minio/mc:latest sh

# Inside the container, set alias
mc alias set local http://minio:9000 minioadmin YOUR_PASSWORD

# List buckets
mc ls local

# Create a new bucket
mc mb local/my-bucket

# Set bucket policy (public read)
mc anonymous set download local/my-bucket

# Set bucket policy (private)
mc anonymous set none local/my-bucket

# Upload a file
mc cp /path/to/file local/my-bucket/

# Download a file
mc cp local/my-bucket/file /path/to/destination/

Using Web Console¶

Access https://s3-console.portugalodyssey.pt
Navigate to "Buckets" in the sidebar
Create, configure, and manage buckets through the UI

Bucket Policies¶

Public Read (Download)¶

mc anonymous set download local/po-files-qual

Private (No Public Access)¶

mc anonymous set none local/po-files-qual

Public Read/Write (Not Recommended)¶

mc anonymous set public local/po-files-qual

File Service Integration¶

Testing File Upload¶

# Upload a test file
curl -X POST \
  -F "file=@/path/to/test.jpg" \
  https://files-qual.portugalodyssey.pt/api/files/upload

# Response:
# {
#   "key": "uuid-filename.jpg",
#   "provider": "minio",
#   "url": "http://minio:9000/po-files-qual/uuid-filename.jpg"
# }

Downloading Files¶

# Download via file-service
curl https://files-qual.portugalodyssey.pt/api/files/{key}/download

# Or directly from MinIO (if bucket is public)
curl http://minio:9000/po-files-qual/{key}

Troubleshooting¶

MinIO Not Starting¶

# Check logs
docker logs po-minio

# Check volume
docker volume inspect po-minio-data

# Restart MinIO
docker restart po-minio

Buckets Not Created¶

# Manually run initialization
docker run --rm --network po-shared-network \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=YOUR_PASSWORD \
  minio/mc:latest sh -c "
    mc alias set local http://minio:9000 minioadmin YOUR_PASSWORD &&
    mc mb local/po-files-qual &&
    mc mb local/po-files-prod
  "

File Service Can't Connect¶

Verify MinIO is running: docker ps | grep minio
Check network connectivity: docker exec po-file-service-qual ping minio
Verify credentials in .env.qualification
Check file-service logs: docker logs po-file-service-qual

Permission Denied¶

# Verify bucket policy
mc anonymous get local/po-files-qual

# Set appropriate policy
mc anonymous set download local/po-files-qual

Backup and Restore¶

Backup MinIO Data¶

# Backup the volume
docker run --rm \
  -v po-minio-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/minio-backup-$(date +%Y%m%d).tar.gz -C /data .

Restore MinIO Data¶

# Stop MinIO
docker stop po-minio

# Restore the volume
docker run --rm \
  -v po-minio-data:/data \
  -v $(pwd):/backup \
  alpine sh -c "cd /data && rm -rf * && tar xzf /backup/minio-backup-YYYYMMDD.tar.gz"

# Start MinIO
docker start po-minio

Security Considerations¶

Change Default Credentials: Always change MINIO_ROOT_USER and MINIO_ROOT_PASSWORD from defaults
Use Strong Passwords: Generate strong, random passwords
Bucket Policies: Keep buckets private unless public access is required
Network Isolation: MinIO is on po-shared-network - only services on this network can access it
Traefik Auth: Console and API are protected by Traefik auth middleware
HTTPS: Always use HTTPS for external access (handled by Traefik)

Migration from AWS S3¶

If you're currently using AWS S3 and want to migrate to MinIO:

Update Environment Variables:

# In .env.qualification
FILE_PROVIDER=minio
S3_ENDPOINT=http://minio:9000
S3_ACCESS_KEY=${MINIO_ROOT_USER_QUAL}
S3_SECRET_KEY=${MINIO_ROOT_PASSWORD_QUAL}
S3_BUCKET=po-files-qual

Migrate Files (optional):

# Using mc to copy from S3 to MinIO
mc mirror s3/your-bucket local/po-files-qual

Restart File Service:

docker compose -f infrastructure/compose/qualification.yml restart file-service-qual

Performance Tuning¶

Storage Backend¶

MinIO performance depends on the underlying storage: - SSD: Best performance - HDD: Acceptable for smaller deployments - Network Storage: May introduce latency

Memory¶

MinIO is lightweight but benefits from: - Minimum: 512MB RAM - Recommended: 1-2GB RAM for production

Disk Space¶

Monitor disk usage:

docker exec po-minio du -sh /data

Set up alerts for disk usage > 80%.

Monitoring¶

Health Check¶

MinIO includes a health endpoint:

curl http://minio:9000/minio/health/live

Metrics¶

MinIO exposes Prometheus metrics at /minio/v2/metrics/cluster. You can integrate this with your Prometheus setup.