Storage and CDN
Moving images off the server and serving them fast.
By default product images live on the store's own disk. Connect object storage and uploads go there instead, served through a CDN — faster for customers, and it stops images filling your server.
When you need this
- Your catalog is large, or you use video.
- You are near your disk quota.
- Customers outside your region complain the store is slow.
A small catalog on local storage is fine. This is not a day-one task.
Choosing a provider
Anything S3-compatible works. Common choices:
| Provider | Notes |
|---|---|
| Cloudflare R2 | No charge for bandwidth out, which is the cost that usually bites. Region is auto. |
| Backblaze B2 | Cheap storage, S3-compatible endpoint. |
| Amazon S3 | The original. Watch egress charges. |
| DigitalOcean Spaces | Simple, with a CDN included. |
Connecting it
Integrations → Storage & CDN:
| Field | What to enter |
|---|---|
| S3 endpoint | R2: https://ACCOUNT.r2.cloudflarestorage.com. Others give you theirs. |
| Bucket | The bucket uploads are written to. Create it first. |
| Region | R2 uses auto; most others want their real region. |
| Access key ID | From the provider's API tokens. |
| Secret access key | Shown once when you create the key. |
| CDN base URL | Optional but recommended, e.g. https://cdn.yourstore.com. Assets are served from here. |
| Max video upload (MB) | Default 100. |
Setting the bucket up
- Create the bucket.
- Make objects publicly readable — customers' browsers fetch them directly.
- Create an API token scoped to that bucket only, with read and write.
- Point a CDN or custom domain at the bucket if your provider supports it.
Scope the token to one bucket. An account-wide key in a store's settings is a much larger blast radius than it needs to be. Most providers make per-bucket tokens easy.
Moving existing images across
If you already have images on local disk, there is a migration that copies them to the bucket and rewrites the URLs. It runs in phases — copy, then rewrite, then clean up — and never deletes anything before verifying it arrived.
- Connect the bucket and confirm a new upload lands there.
- Start the migration.
- Watch the store while it runs. Images stay served throughout.
- Only after it reports done are the local copies removed.
Take a backup first anyway. The migration is careful, but a backup costs you five minutes and removes the question entirely.
Testing it
- Press Test.
- Upload an image to a product.
- Right-click the image on the storefront and check the URL — it should be your CDN or bucket, not your store's domain.
- Open that URL in a private window. If it will not load, the bucket is not public.
Common problems
| Symptom | Cause |
|---|---|
| Uploads fail | Wrong endpoint or region, or the token lacks write permission |
| Upload works, images do not display | Bucket objects are not public |
| Some images load, others do not | Migration part-done, or a stale CDN cache |
| Slow despite the CDN | CDN base URL not set, so files come straight from the bucket |
Still stuck? Message us on WhatsApp — we would rather answer than have you guess.