Skip to content

Amazon S3

Amazon S3 object storage for file uploads, avatars, and media. The extension registers an S3-backed implementation of the platform's FileStorageStrategy interface, so core upload surfaces — avatar uploads, media uploads, presigned browser uploads, and the media-orphan purge — write to and delete from an S3 bucket instead of local disk. It wraps the shared S3Service (SigV4 signing over httpx — no boto3 dependency) and supports an optional CDN URL such as CloudFront for public object URLs.

At a glance
Extension id s3
Category storage
Version 0.1.0
Provides FileStorageStrategy implementation (registered as s3)
External account AWS — Access Key ID + Secret Access Key with access to an S3 bucket

What It Provides

  • File storage strategy — S3StorageStrategy, registered with the strategy resolver as a FileStorageStrategy implementation named s3 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_REGION, S3_ACCESS_KEY, S3_SECRET_KEY, S3_BUCKET — and optionally S3_PUBLIC_URL for CloudFront.
  3. Restart the API. The strategy is constructed once, at extension activation, from those application settings.

Configuration Reference

Key Type Required Secret Description
s3_region string Yes No AWS Region. Defaults to us-east-1.
s3_access_key string Yes No Access Key ID
s3_secret_key password Yes Yes Secret Access Key
s3_bucket string Yes No Bucket Name
s3_public_url string No No CDN URL (optional CloudFront)

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_REGION, S3_ACCESS_KEY, S3_SECRET_KEY, S3_BUCKET, S3_PUBLIC_URL. 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, s3, minio, ...); when core resolves the storage strategy without naming one, the most recently registered implementation is returned.
  • Endpoint selection — the strategy also receives S3_ENDPOINT (application default http://localhost:9000, not part of this extension's config schema). The AWS endpoint https://s3.<region>.amazonaws.com is used only when S3_ENDPOINT is empty, so point S3_ENDPOINT at your S3 endpoint (or clear it) for a real AWS deployment.
  • Public URLs are path-style: <base>/<bucket>/<key>, where the base is S3_PUBLIC_URL when set, otherwise https://<bucket>.s3.<region>.amazonaws.com.
  • Presigned uploads — generate_presigned_url returns a SigV4 query-string presigned PUT URL; 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 a misconfigured bucket 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.