Skip to main content

Media Storage & CDN

All platform media — product images (Medusa), CMS media / blog images / 360° frames (Payload), and generated invoice PDFs (API) — is stored in one S3/B2 bucket and served through a KeyCDN pull zone. Public assets resolve to CDN URLs; private assets (invoices) use short‑lived signed URLs. Every integration is gated on S3_BUCKET, so local dev with no credentials falls back to on‑disk storage and the app keeps working.

Shared environment contract​

Set the same values in each service's env (apps/api/.env, apps/blog-cms/.env, apps/medusa/.env, apps/storefront/.env.local):

S3_ENDPOINT=https://s3.<region>.backblazeb2.com # B2 / MinIO / S3 endpoint
S3_REGION=<region>
S3_BUCKET=<bucket>
S3_ACCESS_KEY_ID=<key>
S3_SECRET_ACCESS_KEY=<secret>
S3_FORCE_PATH_STYLE=true # required for B2 / MinIO
MEDIA_CDN_URL=https://<zone>.kxcdn.com # KeyCDN pull-zone base (origin = the bucket)

Public‑URL rule (everywhere): MEDIA_CDN_URL ? "<MEDIA_CDN_URL>/<key>" : "<bucket public URL>/<key>".

KeyCDN setup​

KeyCDN is a pull zone: create a zone whose Origin URL is the bucket's public base, then set MEDIA_CDN_URL to the zone host (e.g. https://utlsolar-1234.kxcdn.com, or your CNAME). No code change — every asset is then CDN‑served. For private assets that must also be CDN‑cached, enable the zone's Secure Token and sign the URLs; otherwise the API uses S3 presigned URLs directly (bucket origin).

Per-service wiring​

ServiceMechanismFile
Payload (CMS media, logos, blog images, 360° frames)@payloadcms/storage-s3 on the media collection; generateFileURL → MEDIA_CDN_URLapps/blog-cms/src/payload.config.ts
Medusa (product images / thumbnails)@medusajs/file-s3 provider; file_url → MEDIA_CDN_URLapps/medusa/medusa-config.ts
API (invoice PDFs)StorageService — S3 client + presigned signedUrl()apps/api/src/invoices/storage.service.ts
Storefrontconsumes absolute CDN URLs; CDN host added to images.remotePatternsapps/storefront/next.config.ts

Public vs private assets​

  • Public (product images, CMS media, 360° frames): the plain CDN URL.
  • Private (invoice PDFs, future warranty docs): the API issues a short‑lived signed URL (S3 presigned GET, default 10 min). The PDF endpoints (/api/invoices/order/:id/pdf, /api/invoices/:number/pdf) 302‑redirect to it so the bucket/CDN serves the bytes instead of the API streaming them. In local‑disk mode they stream as before.

Enabling it (one-time)​

  1. Provision a bucket (Backblaze B2 / AWS S3 / MinIO) and a KeyCDN pull zone with the bucket as origin.
  2. Set the shared env in all four services.
  3. Install the storage SDKs (gated — only needed once S3 is on; match each app's framework version):
    (cd apps/blog-cms && npm i @payloadcms/storage-s3@3.85.0)
    (cd apps/medusa && npm i @medusajs/file-s3)
    # apps/api already includes @aws-sdk/s3-request-presigner
  4. Restart the services. New uploads land in the bucket and resolve to CDN URLs.

Dev fallback​

With S3_BUCKET unset: Payload/Medusa use local‑disk media and the API writes invoice PDFs under apps/api/.invoices. No cloud account needed — nothing breaks.