Skip to content

MinIO

MinIO object storage for file uploads, avatars, and media. The extension registers a MinIO-backed implementation of the platform's FileStorageStrategy interface, pointing the shared S3-compatible client (S3Service, SigV4 over httpx) at a self-hosted MinIO endpoint. Core upload surfaces — avatar uploads, media uploads, presigned browser uploads, and the media-orphan purge — then read and write objects in your MinIO bucket.

At a glance
Extension id minio
Category storage
Version 0.1.0
Provides FileStorageStrategy implementation (registered as minio)
External account None (self-hosted MinIO server — endpoint + access/secret key pair)

What It Provides

  • File storage strategy — MinioStorageStrategy, registered with the strategy resolver as a FileStorageStrategy implementation named minio when the extension activates, alongside the built-in local backend.
  • The FileStorageStrategy interface covers four operations: upload bytes under a key (returns the public URL), delete an object, build a browser-accessible public URL for a key, and generate a presigned upload URL.
  • The implementation wraps the shared S3Service (backend/vectis/core/s3.py): path-style requests ({endpoint}/{bucket}/{key}) signed with AWS Signature Version 4 over httpx — no boto3/aiobotocore dependency.
  • Nothing else — the package contributes no webhook endpoints, Temporal workflows, schedules, admin pages, GraphQL fields, or event subscriptions.

Setup

  1. Once installed (or dev-linked in development), the extension is discovered at startup. Enable it for a channel from Settings > Extensions (per-channel activation via ChannelExtension).
  2. Set the environment variables the manifest's install hint names: S3_ENDPOINT, S3_PUBLIC_URL, S3_ACCESS_KEY, S3_SECRET_KEY, S3_BUCKET.
  3. Restart the API. The strategy is constructed once, at extension activation, from those application settings.

Configuration Reference

Key Type Required Secret Description
s3_endpoint string Yes No MinIO Endpoint
s3_public_url string Yes No Public URL
s3_access_key string Yes No Access Key
s3_secret_key password Yes Yes Secret Key
s3_bucket string Yes No Bucket Name
s3_region string No No Region. Defaults to us-east-1.

password-typed fields are encrypted at rest (Fernet) and masked as *** in the admin configuration form.

Configuration is read from the environment, not the admin form

The activation hook builds the strategy from application settings (environment variables / .env) with the same key names uppercased — S3_ENDPOINT, S3_PUBLIC_URL, S3_ACCESS_KEY, S3_SECRET_KEY, S3_BUCKET, S3_REGION. The extension defines no hot_reload hook, so values saved through the admin configuration form are stored but nothing hands them to the already-registered strategy. Configure via environment variables and restart.

Permissions

The manifest declares no admin permissions (permissions=[]), so no role assignment is needed.

Operational Notes

  • Who calls it — core resolves the active FileStorageStrategy at call time for avatar uploads (POST /api/upload/avatar), media uploads (POST /upload), presigned upload URLs (GET /upload/presign), CMS image derivative generation, and the daily vectis-gc-media-orphans Temporal schedule (GcMediaOrphansWorkflow), which physically deletes purged media objects through the active backend.
  • Which backend wins — every registered backend keeps its name (local, minio, s3, ...); when core resolves the storage strategy without naming one, the most recently registered implementation is returned.
  • Public URLs are path-style: <base>/<bucket>/<key>, where the base is S3_PUBLIC_URL when set, falling back to the endpoint. A separate public URL matters when S3_ENDPOINT is an internal Docker hostname (e.g. minio:9000) that browsers cannot resolve — which is why the config schema marks it required.
  • Presigned uploads — generate_presigned_url returns a SigV4 query-string presigned PUT URL against the MinIO endpoint; the GET /upload/presign endpoint uses the default 3600-second expiry.
  • Uploads sign with UNSIGNED-PAYLOAD and a 60-second HTTP timeout; deletes treat a 404 as success (idempotent) with a 30-second timeout.
  • Avatar uploads fall back to the built-in local backend when the primary backend raises, so an unreachable MinIO degrades rather than hard-fails that endpoint.
  • The three S3-compatible storage extensions — Amazon S3, MinIO, and DigitalOcean Spaces — all read the same S3_* settings; configure the one that matches your provider. See also Storage Extensions in the developer guide.