Skip to Content

ORBCATALOG DOCUMENTATION

Private media storage

Use one existing private R2 or S3-compatible store without changing the media library.

Choose one store

Without storage settings, Catalog uses the native MEDIA R2 binding. Point that binding's bucket_name at your existing private bucket; no S3 credentials are needed. Uploads, background imports, replacements, use protection and media URLs keep the same behavior. Storage choice does not select an image CDN or transformation service: MEDIA_ORIGIN and MEDIA_TRANSFORM still configure delivery separately.

For AWS S3 or a compatible endpoint, set these server-side Worker vars:

{
  "MEDIA_STORE": "s3",
  "MEDIA_S3_ENDPOINT": "https://s3.eu-central-1.amazonaws.com",
  "MEDIA_S3_BUCKET": "merchant-private-media",
  "MEDIA_S3_REGION": "eu-central-1",
  "MEDIA_MANAGED_ROOT": "orbcatalog/test/"
}

Install MEDIA_S3_ACCESS_KEY_ID and MEDIA_S3_SECRET_ACCESS_KEY as Worker secrets. MEDIA_S3_SESSION_TOKEN is an optional secret for temporary credentials; rotation and renewal remain the operator's responsibility. Locally use an ignored .dev.vars. Never put these values in vars, URLs, logs, browser code or the repository. The S3 mode does not need a MEDIA binding and never falls back to one after an error. The native mode can be selected explicitly with MEDIA_STORE=r2.

The endpoint must be an HTTPS origin without a path, query, fragment or embedded credentials. Requests use path-style bucket addressing and header-based AWS SigV4, not public or presigned URLs; redirects are refused. Use your bucket's actual region and regional endpoint. For R2's S3 API use your account's jurisdiction-appropriate endpoint and region auto; a same-account native binding is simpler. Keep data in the EU. Nothing creates a bucket, account, domain, policy or public-access setting.

Reserve the managed root

MEDIA_MANAGED_ROOT defaults to orbcatalog/. Reserve this previously unused prefix for Catalog alone; choose a separate root per catalog/environment sharing a bucket. It must end in / and contain only nonempty segments of letters, digits, _ or -. Choose it before importing: changing the store or root is not a migration and does not scan, copy or adopt old objects.

Catalog stores originals at {root}{mediaId}, replacement staging at {root}replacing/{mediaId}/{digest}/{attempt} and generated variants at {root}renditions/{mediaId}/{opaque-validator}/{width}.webp. Registered originals stay at their existing keys; only their protected JSON locators are written at {root}locators/{mediaId}.json. Library URLs do not contain the root. Cleanup can list only a single file's rendition prefix; all writes/deletes are root-relative. Existing keys outside the root, including similarly named sibling prefixes, are never overwritten or deleted by managed cleanup. Objects under the reserved root belong to Catalog; do not place unrelated files there.

Selecting a bucket alone does not register its existing originals in the library. There is no bucket browser, scan, bulk copy or direct browser upload. Private-key registration and delivery are separate from store configuration. Already-public CDN files can instead use public media links.

Authorize registration

Registration is disabled by default, including on a new Startup catalog. To enable it, provide MEDIA_REGISTRATION_GRANTS as a server-side JSON object. Each key is an authenticated Source's stable ID, not its name, key, or product-field ownership. Each selection is either an exact key or a directory prefix ending in /:

{
  "MEDIA_STORE_ID": "merchant-images-eu",
  "MEDIA_REGISTRATION_GRANTS": {
    "src_akeneo000002": [{ "prefix": "products/" }, { "key": "campaigns/winter-hero.jpg" }]
  }
}

This grants consent to public library delivery, not just private storage access. Grant only selected shopper-image namespaces. Prefix matching is exact and directory-bounded: products/ does not allow products-backup/. Keys inside the managed root are always refused, even if a selection would allow them. No Source grant permits listing, raw-byte replacement or deletion. Source requests cannot choose a store, endpoint, bucket, public URL or permissions. Provider IAM and these application grants are separate protections; restrict both.

Removing a grant prevents further registration by that Source. It does not withdraw existing library entries or published uses; those keep the ordinary use protection and 30-day library retention behavior.

For the native R2 binding, MEDIA_STORE_ID is mandatory when opting into registration and must remain configured for delivery after grants are removed. A fresh catalog needs neither setting. R2 bindings do not disclose their bucket identity to this adapter, so this ID must identify the physical bucket across deployments and credential changes. Keep it when rebinding the same bucket; change it when binding a different bucket. Do not reuse an ID for another physical store. Changing it is not a migration. The S3 mode derives registration identity from the normalized endpoint origin and exact bucket name; a configured native ID cannot alias a different S3 endpoint or bucket. Keep the endpoint stable when it still denotes the same physical store.

Use Source registerMedia() with bounded metadata rows. The server checks each permitted object's HEAD without copying or reading its bytes. Dimensions are supplied by the Source. All registered originals remain read-only; metadata edits, unregistering and retention cleanup never delete them. A small indexed identity record remains after a library entry is forgotten so registering that same store/key again reuses its media ID.

Use an owned replacement

An editor with content-edit authority opens the file in Media and chooses Use owned copy, then selects new image bytes. The staff API is PUT /panel/media/{mediaId}/owned-copy, with the image as its body. It creates no second library file: the same ID, uses, name, folder, alt text and focal point remain. The new bytes must preserve the image's proportions (1% rounding tolerance) and must not belong to another managed library file; media_exists identifies that file instead. The registered original is never overwritten, deleted or granted management rights.

GET /panel/media/{mediaId} reports replacement: owned-copy for registered files, in-place for managed files, and none for public external references. This is a description of the file, not an authorization grant; the server checks staff authority and current state again on writes. Ordinary PUT /panel/media/{mediaId} still refuses registered originals with media_readonly. Sources cannot call the adoption endpoint or grant themselves management. Repeating adoption with the same bytes is harmless; different bytes after adoption return media_changed, rather than overwriting a concurrent editor's replacement. Open the file again to use ordinary replacement.

Before any storage operation, each replacement attempt commits a private SQL grant and delayed abandonment task together. The grant expires after 15 minutes: this permits abandonment, not an assumption that provider requests have finished. Its unique staging key first receives a small initial marker with create-if-absent. Only an acknowledged, bounded read of that exact marker supplies the validator for the conditional image PUT. The library transaction consumes the active, unexpired grant and transfers accepted bytes to its durable install task, or refused bytes to a discard task. The install task conditionally installs the image, removes the old locator, cleans old variants and queues the media purge. A delayed refusal cannot remove another attempt's required bytes.

Terminal tasks replace only their own stages with a fixed small fence, never delete them. Abandonment revokes the grant under the same library lock, then releases the transaction before fencing storage. Acknowledgment or a bounded read of the exact fence allows the journal row to go; provider failures remain retryable without a finite completion promise. Distinct initial/fence bytes and atomic conditional writes prevent late marker or image PUTs from recreating full images, including after file forgetting. Retain these tiny fences permanently: they are essential lifetime fencing metadata, not disposable temporary objects. Object count and storage/operation costs grow with replacement attempts, even after library files are forgotten. Do not apply deletion lifecycle rules to this prefix. No staging list, bucket scan or journal sweep is used. This guarantees the current object is a fence; bucket version history may retain old full-byte versions and remains the operator's responsibility. Resending the current digest supplies a fresh owned stage, so a retry can repair a missing stage without changing library identity or metadata. If a stage is absent or is no longer the expected image, a bounded read must verify the installed original's SHA-256 digest, size and type before the task can complete; an opaque ETag is no proof. Failure leaves retryable work, not a mutation of the raw original. The Source's durable store/key mapping remembers editorial adoption. Resends return the current owned ID and dimensions without comparing the replacement with the original's metadata. They restore an adopted file during its undo period, but after final forgetting they are explicitly rejected with media_metadata_conflict; the raw original cannot resurrect the removed owned file.

Replacement freshness

Upgrade integrations

Deploy Catalog and its admin together. Update any integration that constructs ProductMedia to preserve the required digest returned by uploads or library reads: the full SHA-256 for owned bytes, null for linked or registered files. Storefronts that use delivered url and srcset values need no URL-building change. Custom URL builders must use the versioned addresses below; the old unversioned routes are removed, not redirected. External PIM URLs are unchanged.

If upgrading a deployment from before managed prefixes, first copy its known Catalog-owned originals into the reserved MEDIA_MANAGED_ROOT, verifying each against its database digest. Selecting the root does not move objects. Do not scan or adopt unrelated bucket contents.

Delivery policy

Owned originals use /media/{mediaId}/{sha256} and Cloudflare renditions append /{width}. Both answer public, max-age=31536000, immutable in browser and edge headers, including HEAD and 304. The full digest avoids shortening the content identity. A replacement changes the URL, not the bytes behind an existing URL. An old or wrong digest returns 404 after replacement; a cache may still answer the original bytes. Missing versions are not cached, so a read while installation is pending cannot poison the new address.

Product, category and library delivery resolve the digest from the authoritative media row. Media-tag purges refresh documents containing image URLs; immutable image responses need no purge. OrbPage reads these delivered URLs, and OrbCart uses the same rendition builder for its line images. Metadata edits do not change an owned image's URL.

Registered private originals are mutable and have no content digest: their /current URLs retain 30-second browser and edge lifetimes, with must-revalidate, stale-while-revalidate=0, stale-if-error=0. Adoption switches delivery to a digest URL. Public external URLs stay exact and retain their host's policy. Independent bunny/imgproxy caches must preserve the versioned source address.

The migration queues media installation tasks for existing owned files. These tasks verify the stored bytes and atomically install digest metadata before versioned delivery can serve them. Drain this work before exposing the upgraded catalog. A library write confirms its transaction, not completion of a failed or delayed storage task. An image already painted in an open page does not refresh itself; document caching policies are unchanged. Local checks are not a deployed-provider SLA.

Deliver registered images

The registration transaction queues the existing media task. Once it runs, originals use /media/{mediaId}/current and Cloudflare variants use /media/{mediaId}/current/{width}. Library thumbnails, product images and srcset use these same addresses. There is no expiring URL, redirect to storage, or original-byte copy. The private bucket is not the public delivery entrypoint: MEDIA_ORIGIN must reach Catalog's media handler (or the configured transformation service in front of it), never the raw bucket or its managed root.

On a miss with private registration enabled, an installed managed original takes precedence over a locator, including a delayed locator task's transient write after adoption. Otherwise Catalog reads the small locator from private storage, parses its bounded JSON, checks its store identity against the active physical store, then streams the registered object's bytes. A mismatched identity, invalid locator or missing object fails closed. No raw key, locator, endpoint or credential is returned. There is no public manifest, bucket listing, or arbitrary-key route. Normal original and variant delivery does not read Postgres. Generated variants remain inside the managed root; their keys encode the complete opaque original ETag without punctuation collisions.

Postgres still owns registration, metadata, uses and deletion permissions. The locator is only a rebuildable delivery projection, never input to a mutation decision. The media task rereads the authoritative row on every retry and after writing a locator, so a delayed task reconciles current registration/forgetting rather than replaying an old locator payload. Metadata edits that affect delivery run the same task. Replaying a file's existing media task rebuilds its locator from Postgres without reading or copying the original. There is no separate projection authority or rebuild pipeline; bulk recovery must enqueue/replay those tasks in bounded batches.

Unregistering retains delivery during the ordinary 30-day undo period, as with uploaded files. Restore uses the same locator; final forgetting removes it and managed variants, never the registered original. Re-registering a forgotten store/key rebuilds the projection under its stable media ID. A failed task remains queued with backoff; wait for delivery readiness after importing or rebuilding, not merely the registration response. CDN/browser copies can outlive origin cleanup until their cache lifetime ends.

Transform choices are unchanged: none serves originals only; cloudflare uses the Images binding and keeps variants in managed storage; bunny and imgproxy keep their existing external URL/transformation conventions and need an operator-configured service that can fetch the controlled original URL. Selecting S3 or CloudFront does not deploy or provide a self-hosted transformer. Already-public CDN references remain their exact supplied URLs and never enter this locator/proxy path.

Cloudflare recipe: private R2, public Catalog delivery

  1. Bind the existing private EU R2 bucket as MEDIA, reserve the managed root, and configure the stable MEDIA_STORE_ID plus selected registration grants. Keep the ID and binding when removing grants to stop new registration.
  2. Keep R2's public development URL disabled and disable/remove public bucket custom-domain access. They are independent access paths. Never expose the root containing private locator JSON. The R2 binding, not an anonymous bucket URL, authorizes storage reads and managed writes.
  3. Set PUBLIC_URL to the approved public Catalog delivery address. Without an override, MEDIA_ORIGIN is its /media path. With a separate media hostname, route only the supported media paths to the same handler; do not attach that hostname directly to R2. Domain/zone/route changes require owner approval.
  4. Use MEDIA_TRANSFORM=none, or configure the Images binding with cloudflare. The existing Workers Cache integration reads the targeted Cloudflare cache header and purges the media tag. Another zone cache needs its own matching cache/purge setup; a custom hostname alone is not proof that caching works.
  5. Respect origin browser/edge TTLs; disable conflicting cache overrides and Always Online for media. Verify the actual cache configuration rather than assuming a targeted header overrides a Cache Rule.

Supported delivery is GET/HEAD, conditional ETag reads, and the closed variant-width ladder when Cloudflare Images is configured. This is public shopper-image delivery, not authenticated downloads. The storage origin remains private even though Catalog's media URL intentionally answers anonymously. R2's S3 API is also usable with signed server-side credentials through the configured subset below; it does not need a public bucket URL.

Official sources, checked 12 November 2026: R2 public-access paths, R2 Workers API, Images binding.

CloudFront recipe: private S3, Catalog as custom origin

  1. Keep the existing regional EU S3 bucket private, with S3 Block Public Access and no anonymous-read policy or website endpoint. Configure Catalog's server-side SigV4 credentials with only the read/managed-root operations below. Catalog, not CloudFront, reads this private bucket in this recipe.
  2. Point a CloudFront custom HTTPS origin at Catalog, with media behavior paths forwarded unchanged to /media/{mediaId}/{version} and /media/{mediaId}/{version}/{width}. Permit viewer GET/HEAD only, require HTTPS, and do not forward viewer credentials or expose panel/sync routes through a media-only distribution. Set MEDIA_ORIGIN to the distribution's approved /media address. The Catalog delivery entrypoint is deliberately public; this recipe does not claim CDN-only access to that entrypoint. Direct storage access is what must be denied.
  3. Use a reviewed custom policy with Minimum TTL=0, Default TTL=0, Maximum TTL=31536000, or disable caching until measured. CloudFront reads the ordinary Cache-Control: one year for digest URLs and 30 seconds for /current. Do not strip the latter's explicit stale-if-error=0. Configure error caching as zero. Do not forward arbitrary query strings into the cache key for these parameter-free paths. Test ETag revalidation with the actual policy.
  4. CloudFront does not automatically honor Cloudflare-CDN-Cache-Control, CDN-Cache-Control or Catalog's Cache-Tag purges. This runtime has no CloudFront invalidation adapter. A second Cloudflare cache at the custom origin is another freshness layer. Disabling CloudFront caching does not eliminate browser caching. Replacement measurements and provider invalidations remain separate acceptance work; do not infer them from these delivery fixtures.

CloudFront does not supply Catalog transformations: none remains original-only, and cloudflare still needs Catalog's Images binding. Other transform services keep their existing contracts; this recipe installs none.

This custom origin is not an S3 OAC origin. AWS S3 origin access control applies when CloudFront actually uses a supported regular AWS S3 bucket origin, signs requests (always), and the bucket policy scopes s3:GetObject to that distribution's service principal/SourceArn. It does not apply to a Catalog HTTP origin, an S3 website endpoint, R2, or arbitrary S3-compatible endpoints. Direct S3 OAC delivery of raw keys is not a replacement for Catalog's media-ID locator route, and exposing its managed root would leak locator JSON. Existing independently managed public CDN links are a separate model.

Official sources, checked 12 November 2026: S3 Block Public Access, CloudFront S3 OAC scope, CloudFront TTLs and origin headers.

Cache-policy sources, checked 12 November 2026: Cloudflare header precedence, Cloudflare stale directives and Always Online.

Required provider operations

This is a defined subset, not a promise that every S3 feature or vendor works:

OperationRequired behavior
HeadObject / native headExisting objects return byte length, Content-Type and quoted ETag; missing objects return 404/null. Permission errors are failures, not missing files.
GetObject / native getStream the bytes with the same metadata; never buffer a whole original to serve it.
PutObject / native putStore the supplied bytes and Content-Type. If-Match atomically refuses stale targets; If-None-Match: * atomically refuses existing targets (HTTP 412/native null). AWS missing If-Match targets, concurrent deletion and current delete markers return 404 NoSuchKey, also a conditional refusal. Other 404s and conflicts (409) remain failures, not success.
ListObjectsV2 / native listHonor the exact prefix and opaque continuation cursor. S3 uses encoding-type=url, decodes keys once, and preserves tokens as opaque XML text.
DeleteObject / native deleteDelete exactly the named managed keys; deleting a missing key succeeds. No bucket or version-history deletion.

Lists request 100 keys per page and stop with an error beyond 1,000 keys or 20 pages. Each S3 listing body is capped at 512 KiB. Repeated/missing continuation tokens, malformed listings and keys outside the requested prefix fail closed. Deletes accept at most 1,000 keys: native R2 uses a bounded batch; S3 sends individual deletes sequentially, with no unbounded fan-out. Normal cleanup concerns one library file, not the size of the merchant's bucket. Partial deletion is safe to retry.

An ETag is an opaque validator, not a content digest: multipart uploads and encryption can make it unlike an MD5. Catalog's byte digest remains independent. Keys containing spaces, Unicode, literal %, +, ?, # and & are encoded as key data, not URLs. S3 keys with a complete . or .. path segment or a backslash are outside this adapter's supported subset.

First managed installation uses atomic create-if-absent, never an unconditional overwrite after a missing HEAD. Conditional refusal rereads authoritative state before retrying. Provider operation references: S3 PutObject preconditions, R2 conditional operations.

Conditional-write 404 bodies are parsed only up to 16 KiB. Only a valid XML error with code NoSuchKey is normalized to a refused conditional write; a missing bucket, permission error, empty/malformed response or oversized body remains a redacted failure. An unconditional 404 is never a conditional refusal.

Grant only GetObject for originals the operator intends to register, and GetObject, PutObject, DeleteObject within the reserved managed root. On AWS, missing HEAD/GET requests return 404 only when the principal has s3:ListBucket permission on the bucket; otherwise AWS can answer 403. Restricting ListBucket solely to cleanup prefixes can therefore break missing-original and missing-rendition checks. The AWS setup requires bucket-level s3:ListBucket without a cleanup-only s3:prefix condition, alongside the scoped object grants. This allows the credential holder to enumerate bucket key names, though Catalog itself still lists only the bounded per-file cleanup prefixes. If that disclosure is unacceptable, use a separate private bucket/native binding rather than treating 403 as absence. Confirm any narrower policy against the intended provider before acceptance; permission failures are never swallowed. Bucket policies and credentials must enforce the object limits; the adapter does not install them. Do not grant account-wide administration. ACL changes, multipart upload APIs, directory buckets, requester-pays, retention overrides, encryption headers and version-history management are not implemented. Bucket-default encryption is left to the provider; versioned buckets may retain old bytes after a normal delete.

Acceptance boundary

The local storage-boundary test exercises native R2 through Wrangler's local workerd binding and a synthetic S3 HTTP fixture: missing reads, metadata, streamed reads, accepted/rejected conditional writes, replacement staging, pagination beyond 100 keys, encoded keys/tokens, bounded cleanup and preservation of foreign keys. It also checks failed access, conflicts, redirects, malformed listings and redacted transport errors. Neither fixture is a live provider probe.

Live AWS S3 and R2 S3 acceptance remains blocked until approved EU synthetic fixtures and credentials are available. Run the same operation sequence, including stale conditional refusal and foreign-key preservation, before enabling another compatible provider. CloudFront/private delivery acceptance is separate and has not been established by these tests. No live resources are created by the local tests.

The delivery flows additionally prove stable original/variant URLs, GET/HEAD/304, distinct opaque validators, zero SQL statements on image delivery, store-mismatch refusal before raw reads, projection retries/rebuild, retention cleanup, and exact external-CDN URLs using storage/image-service fixtures. They do not prove provider access policies, CDN cache behavior, invalidation or a measured freshness bound.

Protected-origin/CDN acceptance remains blocked without explicitly authorized EU synthetic provider fixtures, credentials and delivery endpoints. For each recipe, record (without secrets/raw private keys) the provider, region, configured cache policy, timestamp and results of: anonymous storage GET/HEAD denied; signed server HEAD/GET successful; registered public original GET/HEAD/304 successful; each advertised variant successful where supported; missing/invalid IDs unable to retrieve raw keys/locators; store mismatch denied; original preserved after unregister/forget; cold/warm CDN reads and replacement revalidation observed with Age/cache-status/ETag and elapsed time. Distinguish actual origin and CDN responses from local fixtures. Do not create resources or alter bucket/account policies merely to complete this checklist without approval.

On this page