Your own storage and CDN
By default, Crumbcast keeps your videos in its own storage. On the Business plan, your organisation can keep them in an S3-compatible bucket of its own instead (AWS S3, Cloudflare R2, Backblaze B2, Wasabi, MinIO or any other), with or without a CDN in front. Your provider bills you for that bucket, so what's kept there counts toward neither your Crumbcast storage nor your delivery.
Storages belong to the organisation. Its admins add them in the dashboard, under
Settings → Storages. API tokens can't manage them: a token's 403 names them among
what no token may do (Access).
This page covers what to set up on your provider's side, what to enter in Crumbcast, the caveats that come with a bucket of your own, and what to do when the Test button says no.
Where Crumbcast keeps your videos
Crumbcast's own storage is in a region. Where it offers more than one, an organisation's admins pick its region under Settings → Storages. New videos and live streams go there from then on. Videos already kept stay where they are and keep playing as before.
Choose how files reach viewers
A storage reaches viewers in one of three ways. Which one you choose decides which videos it may keep:
| Setup | Viewers get | May keep |
|---|---|---|
| No public URL | Short-lived signed URLs from the bucket's own S3 endpoint | Everything |
| A public URL (the bucket's public address, or a CDN in front of it) | Lasting links at that address, as they are | Only public videos and live streams, in clear |
| A public URL whose CDN signs links (CloudFront signed URLs or Bunny token authentication) | Short-lived links through the CDN, each signed | Everything |
A signed or password video, or one that's encrypted or has forensic watermarks, needs
the first or the third. Its files must never be reachable at a lasting address. An
encrypted video's source is kept in the bucket unencrypted, and a forensic video's viewer
may reach only their own copy's segments.
If you're not sure, start with no public URL. It works for every video, and you can add a CDN later.
Playlists, captions, encryption keys and chapters always come from Crumbcast, whichever you pick. Only the media files (segments, thumbnails, storyboards, GIFs) come from your storage.
Prepare the bucket
The bucket
- Its own bucket, used only by Crumbcast. Crumbcast writes at the top of it, a folder for each project, and deletes a video's whole folder when the video is deleted.
- Private. Don't make it publicly readable, even when a CDN will serve it. Only the CDN reads it then.
- A lowercase name without dots, such as
acme-video. Dots break TLS on many providers' bucket addresses. - No versioning or object lock. With either, deleting a video leaves its files behind, and you're still billed for them.
- No expiry lifecycle rules on its objects. A rule that deletes old objects deletes your videos' files. A rule that aborts incomplete multipart uploads after a few days is the one worth adding: it clears uploads that were started and never finished.
An access key
Make a key for this bucket only, which may:
| Action | For |
|---|---|
s3:PutObject, s3:GetObject | Uploading, encoding and reading files |
s3:DeleteObject | Removing a deleted video's files, and replaced ones |
s3:ListBucket | Finding every file of a video to delete it |
s3:AbortMultipartUpload, s3:ListMultipartUploadParts | Uploads in parts |
On AWS, as a policy for the key's IAM user (acme-video is the bucket):
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject", "s3:AbortMultipartUpload", "s3:ListMultipartUploadParts"],
"Resource": "arn:aws:s3:::acme-video/*"
},
{
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::acme-video"
}
]
}
Other providers name these "read and write" or "object read & write" for one bucket. Crumbcast keeps the key for good. It encodes, plays and deletes with it for as long as a video is in the bucket.
CORS
Browsers load video files from your storage, and the dashboard uploads to it directly,
in parts. Both need the bucket's CORS rules to allow your Crumbcast's address
(https://your-crumbcast below):
[
{
"AllowedOrigins": ["https://your-crumbcast"],
"AllowedMethods": ["GET", "HEAD", "PUT"],
"AllowedHeaders": ["*"],
"MaxAgeSeconds": 3600
}
]
That's the AWS, R2 and Wasabi format. Others take the same fields in their console. The
origin is the address without a path or trailing slash. Uploads don't read parts' ETag,
so the rules needn't expose it.
With a CDN in front, the CDN answers viewers, so it needs CORS too (see below). The bucket's rules still matter for uploads, which go to the bucket's endpoint, never through the CDN.
Embedded players are the exception: they load files inside Crumbcast's own frame, so you don't need to list your own site's domain.
Add it in Crumbcast
In Settings → Storages, choose Add new storage:
| Field | What to enter |
|---|---|
| Title | A name for it, which members see when they pick where a video goes |
| Endpoint URL | The provider's S3 API address, without the bucket in it: https://s3.eu-central-1.amazonaws.com, https://<account>.r2.cloudflarestorage.com, https://s3.us-west-004.backblazeb2.com |
| Access Key, Access Secret | The key above. The secret is kept encrypted and never shown again |
| Bucket Name | The bucket's name alone |
| Public URL (optional) | Empty for signed URLs; else the bucket's public address or the CDN's, files' paths following it |
| CDN signing | Only for a CDN that serves signed links only (below) |
Both URLs must be https:// and resolve to a public internet address: Crumbcast's
servers connect to them as well as viewers' browsers.
The region comes from the endpoint. Crumbcast signs requests for the region in the
endpoint's host name (s3.<region>.… or s3-<region>.…), and for us-east-1 when it
names none. R2, MinIO and most others accept that. On AWS, use the bucket's regional
endpoint, never https://s3.amazonaws.com, unless the bucket is in us-east-1.
Then choose Test on the new storage. It writes a test file, reads it back the way a viewer would, checks CORS for your Crumbcast's address, and deletes it. With a CDN that signs links, it also checks the CDN refuses the file unsigned. "Storage works for uploads and playback" means all of it passed. Anything else names the step that failed; see Troubleshooting.
The Test doesn't send a PUT from a browser, so it can't check CORS for uploads. Upload a
short video from the dashboard to check them.
Send videos to it
A video's storage is picked when it's made:
- The organisation's default. Set as default on a storage sends every project's new videos there, unless the project picked another.
- A project's default. A project's Settings → General → Default destination for new assets overrides the organisation's.
- A workflow's. A workflow with a storage puts its videos there.
- Each upload's. The dashboard's upload asks where when there's a choice; the API
takes
storage_id(Upload videos).GET /api/v1/projects/{id}/storages/lists what may be picked.
Videos already uploaded stay where they are. The form only offers what a storage can keep: with a public URL, signed, password and encryption choices are greyed out, and say why.
Put a CDN in front
A plain public URL
Any CDN, or the bucket's own public address, works as a public URL for public videos.
Point the CDN at the bucket, and enter its address as the public URL. Crumbcast links each
file as <public URL>/<path in the bucket>, so the CDN must serve the bucket's paths
unchanged.
- The CDN needs CORS for your Crumbcast's address: forward the bucket's CORS headers, or set them on the CDN.
- Keep the
vquery parameter in the cache key. A replaced thumbnail keeps its file name and gets a new?v=, and a CDN that ignores it serves the old picture. - Don't redirect: the address must answer files with
200, not301to another address.
A storage with a plain public URL can't keep signed, password, encrypted or forensic videos. Adding a public URL to a storage that holds one is refused.
A CDN that signs links
A CDN that serves only signed links may keep every kind of video. Crumbcast signs each file's link separately, so a viewer can reach exactly what they may watch. Two are supported:
CloudFront
- A distribution whose origin is the bucket, reached with Origin Access Control. The bucket stays private.
- An RSA 2048 key pair. Add its public half under CloudFront → Public keys, and put it in a key group.
- In the distribution's behaviour, Restrict viewer access to that key group.
- A cache policy that leaves
Expires,SignatureandKey-Pair-Idout of the cache key and keepsvin it. With those three in the key, every viewer's link is a cache miss. - A response headers policy with CORS for your Crumbcast's address.
- In Crumbcast: the distribution's address as the Public URL, CloudFront signed
URLs, the public key's ID (from Public keys, not the key group's), and the
private key in PEM, the whole
-----BEGIN … KEY-----block.
Bunny
- A pull zone whose origin is the bucket, with S3 origin authentication. The bucket stays private.
- Under Security, turn Token authentication on and copy its key.
- Query string caching: vary by
vonly. - CORS headers for your Crumbcast's address.
- In Crumbcast: the pull zone's address as the Public URL, Bunny token authentication, and the token key.
Then Test. Its last step asks the CDN for the file without a signature, and fails if the CDN serves it. A CDN that serves unsigned files would let anyone read what only signed links should reach.
Cloudflare in front of R2 has no signed links of its own. Use R2 with no public URL for private videos, or Cloudflare as a plain public URL for public ones.
Caveats
A video never changes storage. Its storage is set when it's made. To move videos to a new bucket, upload them again there. Changing a storage's Endpoint URL or Bucket Name doesn't move anything. Its videos then look for their files in the new place, so change them only to point at a copy of the same bucket.
A storage holding videos can't be deleted. Delete its videos first. Deleting a storage only makes Crumbcast forget it: what's in the bucket stays there.
Deleting a video deletes its files. Everything under its folder goes, in the
background. If the bucket refuses (a key without s3:DeleteObject or s3:ListBucket,
object lock), the video is gone from Crumbcast and its files stay in the bucket.
Keep the key working. Encoding, playback, thumbnails and deletes all use it. Revoke it and every video in the storage stops playing. To rotate it, make the new key, enter it in Update Storage (an empty secret keeps the current one), test, then revoke the old one.
What's in the bucket. A project's videos are at <project id>/<video id>/: the source
as uploaded, each encoding's segments, thumbnails, captions and GIFs. Live streams'
broadcasts are at <project id>/live/<live stream id>/. Test files are written to
.biscuit-storage-test/ and deleted straight away. Don't add, rename or remove files
there yourself.
An encrypted video's source is in clear. Encryption covers what viewers get. The uploaded source stays in the bucket as it was, which is why encrypted videos need a storage without an unsigned public URL. Whoever can read your bucket can read it.
Live streams write as they broadcast. Each segment goes to the storage as it's made, so a storage far from the live servers, or a slow one, adds delay for viewers. A live stream's storage is picked as a new public video's would be.
Changing how a storage is reached is checked. A storage can't get an unsigned public URL, or turn CDN signing off, while it holds a video that needs neither ("Signed playback needs a storage without a public URL…"). Changing its signing from CloudFront to Bunny, or back, needs the new CDN's key.
Links last minutes, not forever. A signed link works for as long as the viewer's playback, rounded up to the next 10 minutes, so viewers in the same 10 minutes share a link and the CDN's cache. Don't copy one into another page; use the video's links there.
Your provider's bill. Crumbcast doesn't count what's in your storage, so its usage page doesn't show it. Your provider bills storage, requests and traffic. Every segment a viewer plays is a request, and without a CDN every byte is egress from the bucket.
Plans. Your own storage is on Business. If the organisation moves to a plan without
it, storages already added keep working. Only adding new ones is refused (402).
Troubleshooting
What the Test says
| The Test says | What's wrong | Fix |
|---|---|---|
| … must use https | The endpoint or public URL is http:// | Use the provider's https:// address |
| … can't be resolved | The host name doesn't exist | Check for typos, and that the endpoint has no bucket name or path in it |
| … resolves to a private or internal address | It's on a private network (a MinIO at home, a 10.… address) | Put it at a public address. Crumbcast's servers must reach it over the internet |
| Storage endpoint rejected: … | The endpoint isn't a valid URL | Enter the API's address, starting https:// |
| Could not write to the bucket: … AccessDenied | The key may not PutObject there | Check the key's permissions, and that it's for this bucket |
| Could not write to the bucket: … InvalidAccessKeyId | The access key doesn't exist at this provider | Check the key, and that the endpoint is this provider's |
| Could not write to the bucket: … NoSuchBucket | The bucket name is wrong, or it's in another account or region | Check the name, and the endpoint's region |
| Could not write to the bucket: … SignatureDoesNotMatch | The secret is wrong, or has a space copied with it | Paste the secret again |
| Could not write to the bucket: … AuthorizationHeaderMalformed, or a region is named | The endpoint's region isn't the bucket's | Use the bucket's regional endpoint (s3.<region>.…) |
| Could not read the test file via its signed URL (HTTP 403) | The key may write but not GetObject | Add s3:GetObject |
| Could not read the test file via its public URL (HTTP 403) | The public URL doesn't serve the bucket's files | Check the CDN's origin, or make the address serve the bucket |
| … via its public URL (HTTP 404) | The public URL serves a different place | Files must be at <public URL>/<path in the bucket>. Check whether the public URL needs the bucket name in it, or has one too many |
| … (HTTP 301) or (HTTP 302) | The public URL redirects | Enter the address it redirects to |
| … via its CDN's signed URL (HTTP 403) | The CDN doesn't accept Crumbcast's signature | CloudFront: the key ID is the public key's, the key group is on the behaviour, the PEM is its pair. Bunny: the token key is the pull zone's, copied whole |
| The bucket's CORS rules don't allow … to load files | CORS doesn't answer for your Crumbcast's address | Add the CORS rules, on the CDN too if there's one. The origin must match exactly, without a trailing slash |
| The CDN serves files without a signature | Signing is set in Crumbcast but not on the CDN | Restrict viewer access (CloudFront) or turn token authentication on (Bunny) |
| Could not reach the storage: … | Crumbcast couldn't connect or finish TLS | Check the address works from outside your network, and its certificate is valid for that name |
Other problems
Uploads stop at 0%, or fail straight away. The browser can't PUT to the bucket. The
browser's console says "blocked by CORS policy". Add PUT and your Crumbcast's address
to the bucket's CORS rules, then upload again. Uploads from your own code, server side,
don't need CORS.
"The upload couldn't be started in the storage". The key may not start a multipart
upload: it needs s3:PutObject on the bucket's objects.
"The storage couldn't put the upload together". Every part arrived, but the key
can't list them: add s3:ListMultipartUploadParts.
Every video in the storage stopped playing at once. Its key was revoked or rotated, or the bucket's CORS rules changed. Run the Test again: it names which.
Through a CDN that signs links, playback is slow to start or fails for some viewers.
The cache key holds the signature. Keep Expires, Signature and Key-Pair-Id
(CloudFront) or token and expires (Bunny) out of it, and v in it.
An old thumbnail keeps showing. The CDN ignores ?v=. Add v to its cache key, then
purge the thumbnail once.
A choice is greyed out in the upload form ("Signed playback needs a storage without a public URL, or with a CDN that signs its links"). The storage the video would go to has an unsigned public URL. Pick another storage, or set CDN signing up on this one.
Changing a storage answers "A new CDN key is needed when its signing changes". Enter the new CDN's key along with its kind of signing.
Deleted videos' files are still in the bucket. Check the key has s3:DeleteObject
and s3:ListBucket, and that the bucket has no object lock or retention. With
versioning on, the files are kept as old versions: delete those, or turn versioning off.