S3 Cloud Storage Bucket

Published on

S3 Cloud Storage Bucket

Selfhost Podcasting can upload episode media to S3-compatible storage and publish the bucket URL in the podcast feed.

Supported providers in the admin UI

  • Cloudflare R2.
  • Amazon S3.
  • Wasabi.

The S3 handler also contains support paths for S3-compatible endpoints when configured by code.

Open settings

  1. Open a podcast.
  2. Go to Connect Services.
  3. Open S3 Buckets.
  4. Enable Use S3 Bucket to store your podcast.
  5. Choose the provider.
  6. Enter required credentials and delivery information.
  7. Click Save Connection.

Required fields

Common:

  • Access Key.
  • Secret Key.
  • Bucket Name.

Cloudflare R2:

  • Account ID.
  • Public Domain for Resources.
  • Endpoint is generated from the account ID when not provided.

Amazon S3:

  • Region.

Wasabi:

  • Region.

Credential storage

Credentials are encrypted before storage using keys derived from the WordPress authentication key and salt. If WordPress salts change, the plugin may be unable to decrypt the saved credentials and will ask you to re-enter configuration.

Upload behavior

When bucket storage is enabled:

  • Episode media can be queued for upload after save or from the media upload action.
  • Uploads run through the background queue.
  • Large local files can use multipart upload.
  • Uploaded objects are verified by object metadata.
  • Delivery URLs are checked with HEAD or range GET requests.
  • The feed uses the bucket URL only when it is safe to publish.
  • Replaced media can be re-uploaded when media changed is checked.
  • Deleted episodes can queue bucket object cleanup.

Local deletion

If Delete audio after S3 upload is enabled, the local media file can be removed after successful upload. Do this only when your bucket delivery URL is reliable and backed up.

Background job safety

Repeated upload failures can pause uploads for a podcast without discarding queued work. Use Resume background jobs after fixing credentials, permissions, bucket policy, object ACL, public domain, or network issues.

Public delivery requirements

Podcast apps must be able to fetch the media URL directly. Make sure:

  • Bucket policy or object ACL allows public reads where required.
  • Custom domain points to the bucket.
  • HTTPS works.
  • Range requests work for large media.
  • The public domain is not the private API endpoint unless your provider documents it that way.

Troubleshooting

Connection test fails

Check provider, bucket, region/account ID, access key, secret key, and endpoint.

Upload succeeds but feed still uses local media

The delivery URL may not be publicly verified. Fix public access or use the sh_podcasting_publish_bucket_url filter if you intentionally override this behavior.

Uploads pause

Open the podcast Error Log, fix the underlying issue, then use Resume background jobs.