MinIO Quick Start Guide¶

Overview¶

MinIO provides S3-compatible object storage for the file-service. Since W2 B-2 (Riff #36, 2026-04-30), MinIO runs per-env, not shared: - minio-qual lives in qualification.yml, owns volume po-minio-data-qual, bucket po-files-qual - minio-prod lives in production.yml, owns volume po-minio-data-prod, bucket po-files-prod

Credentials are env-suffixed: MINIO_ROOT_USER_QUAL / MINIO_ROOT_PASSWORD_QUAL (in .env.qual); MINIO_ROOT_USER_PROD / MINIO_ROOT_PASSWORD_PROD (in .env.prod). The shared stack no longer hosts MinIO.

VPS migration recipe (run once per VPS to move from old shared layout): see DEPLOYS.md § "VPS migration recipe — MinIO per-env split".

Quick Setup¶

1. Update Environment Variables¶

Add to .env.qual:

MINIO_ROOT_USER_QUAL=minioadmin
MINIO_ROOT_PASSWORD_QUAL=REPLACE_ME_STRONG_PASSWORD

Add to .env.qualification:

MINIO_ROOT_USER_QUAL=minioadmin
MINIO_ROOT_PASSWORD_QUAL=REPLACE_ME_STRONG_PASSWORD_MATCH_SHARED

2. Start Shared Infrastructure¶

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

3. Verify MinIO is Running¶

docker ps | grep minio
# Should show: po-minio and po-minio-init

4. Check Bucket Initialization¶

docker logs po-minio-init
# Should show: "MinIO initialization complete!"

5. Restart File Service¶

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

Verification¶

Test File Upload¶

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

Access MinIO Console¶

The MinIO consoles are not exposed via Traefik — admin access goes over SSH tunnel:

# qual
ssh -L 9001:po-minio-qual:9001 root@<vps>
# then open http://localhost:9001 — login with MINIO_ROOT_USER_QUAL / MINIO_ROOT_PASSWORD_QUAL

# prod
ssh -L 9002:po-minio-prod:9001 root@<vps>
# then open http://localhost:9002 — login with MINIO_ROOT_USER_PROD / MINIO_ROOT_PASSWORD_PROD

Each MinIO instance owns one bucket: po-files-qual for qual, po-files-prod for prod. The buckets are created on first start by the matching minio-init-{qual,prod} container.

What Changed¶

✅ MinIO instances split per-env (W2 B-2, Riff #36, 2026-04-30)
✅ Volumes split: po-minio-data-qual and po-minio-data-prod
✅ file-service-prod migrated from AWS S3 to self-hosted MinIO
✅ Init containers split: minio-init-qual and minio-init-prod
✅ Env templates updated; AWS_* dropped from prod template

Next Steps¶

See detailed documentation: docs/developers/services/file-service/minio-setup.md
Configure bucket policies as needed
Set up backups for MinIO data volume