Connecting an S3-compatible bucket to freedam does two different jobs, and the product supports both. As an import source, it pulls the files already sitting in a bucket into the library — with metadata, previews, search, and versioning layered on top — and keeps them in sync as the bucket changes. As a storage backend, S3-compatible object storage is where a self-hosted freedam deployment can keep the assets themselves.

What it does

The S3 connector is one of freedam's built-in Data Sources (Admin → Sources). It works with AWS S3 and with any S3-compatible object store — MinIO, Wasabi, and similar — via a configurable endpoint URL. A source remembers what it pulled last time: on every refresh, new objects are ingested as assets, changed objects become a new version of the existing asset, and objects that have disappeared upstream are handled by the deletion policy you choose (soft-archive and restore automatically if they return, or additive — never remove anything).

The connector is strictly read-only. freedam only needs s3:GetObject and s3:ListBucket; it never writes back to your bucket, and the docs recommend an IAM policy that grants nothing more.

How it works

Creating a source takes a short form: bucket name, region, access key and secret key (stored encrypted, never logged), an optional base path prefix to restrict ingestion to part of the bucket (for example products/2026/), and an optional endpoint — leave it blank for AWS, or enter the full URL for an S3-compatible server. A Test connection button verifies bucket access before you save anything.

From there, the source behaves like every other freedam Data Source. You map object folders to collections, optionally match filenames against a catalog spreadsheet so files inherit product metadata, and set a cron schedule for automatic refreshes — or refresh manually. Before committing to a full import you can run a small sample or a dry run that computes the complete plan without writing anything, and a live preview shows exactly where each file would land. Unchanged objects are skipped on re-sync, so repeated refreshes of a stable bucket cost almost no bandwidth.

On the storage-backend side: freedam's filesystem configuration supports S3-driver disks with custom endpoints and path-style addressing, so a self-hosted deployment can keep originals and media on any S3-compatible store rather than local disk. This is configured through environment variables at deployment time, independent of any import sources you set up in the admin UI.

Good to know

• Least privilege works. A read-only IAM user with s3:GetObject and s3:ListBucket on the one bucket is all the connector needs. Do not grant write permissions.
• Safety stops are built in. If a refresh sees the bucket listing shrink by more than half, the run pauses for review instead of archiving your library over a transient listing error. Repeated authentication failures disable the source and notify admins rather than filling the run log.
• Versioning is real versioning. A changed object becomes a new version of the same asset — links, collection memberships, and shares stay intact. Byte-identical re-uploads are detected and skipped.
• Sources require the admin.sources permission to configure.

The connector setup and mapping options are covered in depth in the documentation. Running self-hosted and weighing storage options? Get in touch.