Atlas Media Offloader

Skildring

Atlas Media Offloader moves your WordPress uploads to S3-compatible object storage, rewrites the URLs so visitors are served from the bucket (or a CDN in front of it), and can pull everything back to local disk on demand.

It was written for libraries measured in gigabytes, where the interesting question is not «can it upload a file» but «what happens when the upload is interrupted». Every transfer is resumable, every deletion is preceded by a verification, and the whole thing is safe to interrupt at any point.

What it does

• Move media to the bucket. In bulk, or automatically as each new file is uploaded.
• Bring media back. In bulk, or per attachment. Files are restored byte-for-byte.
• Serve from the bucket or your CDN. Attachment URLs, responsive srcset entries, image sizes, and the media modal are all rewritten.
• Optionally delete local copies. Only after every single file has been re-checked in the bucket and its byte count matches.
• Private buckets. Media URLs are signed, with a configurable lifetime.
• See the state of every image. The Media tab lists each attachment with its offload status and, when something was skipped, exactly why — with per-image «offload now», «re-check» and «download» buttons.
• Know what happened. An activity log records every bulk transfer and every automatic offload, in plain English.
• Clean up after itself. Deleting an attachment deletes its objects; cropping an image removes the objects the old crop left behind.
• Check your own work. wp atlasmo verify re-reads every recorded object out of the bucket and compares its size; --repair re-uploads anything missing or truncated.
• WP-CLI. wp atlasmo offload, wp atlasmo download, wp atlasmo verify, wp atlasmo status, wp atlasmo test.

Providers

• Amazon S3
• DigitalOcean Spaces
• Any other S3-compatible endpoint (Cloudflare R2, Wasabi, Backblaze B2, MinIO, …) via a custom endpoint URL

Languages

Fully translation-ready, and ships with Spanish, French and German translations of the main interface. Anything not yet translated falls back to English.

Built for large libraries

Moving a lot of media through PHP means the work will be interrupted and this plugin is designed around that rather than in spite of it:

• Large files upload in parts and resume from the last completed part. A 2 GB file that runs out of time picks up where it stopped instead of starting over. The worst case for a hard crash is re-sending 32 MB.
• Local files are never deleted before the copy in the bucket has been verified. Uploading, verifying, recording and deleting happen strictly in that order. A crash between any two of them leaves you with a redundant local file, never a missing one.
• The transfer keeps running with the tab closed. Three independent triggers drive it, so it does not depend on WP-Cron — which most managed hosts disable.
• Only one worker ever runs at a time, so nothing is ever uploaded twice, even when a cron run, a browser tab, and WP-CLI all try at once.
• A wrong secret key pauses the transfer rather than failing your entire library one file at a time.
• Progress, failures and their reasons are all shown, and failed items can be retried.

No third-party libraries

The plugin talks to S3 directly. It implements AWS Signature V4 itself, uses the WordPress HTTP API for transport, and WP_Filesystem for file access. There is no AWS SDK, no Guzzle, no Action Scheduler, and no build step. The whole plugin is plain PHP and a little vanilla JavaScript.

When we need this plugin?

• Your uploads folder has outgrown your hosting plan.
• You are moving to a container or serverless host where local disk is not persistent.
• You want media served from a CDN without a caching plugin in the middle.
• You are migrating hosts and want the media somewhere neutral first.
• You need media behind signed, expiring URLs.

Customizable Features

• Provider preset (Amazon S3, DigitalOcean Spaces, or a custom endpoint)
• Path-style vs. virtual-hosted addressing
• A key prefix, so media can live in a folder inside the bucket
• A CDN domain to serve from
• Public bucket, or private with signed URLs and a configurable lifetime
• Automatic offload of new uploads, on or off
• Deletion of local copies after verification, on or off
• Multipart part size (5–16 MiB)
• Rewriting of hard-coded upload URLs in old post content

Storing credentials in wp-config.php

This is the recommended setup. Anything defined here overrides the settings screen, is shown read-only, and never touches the database:

define( 'ATLASMO_PROVIDER',   'aws' );
define( 'ATLASMO_ACCESS_KEY', '...' );
define( 'ATLASMO_SECRET_KEY', '...' );
define( 'ATLASMO_BUCKET',     'my-bucket' );
define( 'ATLASMO_REGION',     'us-east-1' );

Optional: ATLASMO_ENDPOINT, ATLASMO_PATH_STYLE, ATLASMO_CDN_DOMAIN, ATLASMO_PRIVATE.

If you enter the secret key in the settings screen instead, it is encrypted with AES-256-GCM using your site’s security salts before being stored, and is never rendered back to the page. Rotating AUTH_KEY or SECURE_AUTH_KEY will invalidate it, and the plugin will tell you so rather than silently failing.

Bucket permissions

The plugin needs exactly five actions. Do not grant it more:

s3:PutObject, `s3:GetObject`, `s3:DeleteObject`, `s3:ListBucket`, `s3:AbortMultipartUpload`

Hooks for developers

• atlasmo_extra_files — add sibling files (WebP/AVIF conversions, etc.) to an attachment’s upload set.
• atlasmo_skip_auto_offload — skip automatic offload for a particular attachment.
• atlasmo_keep_remote_on_delete — keep the objects in the bucket when an attachment is deleted.

System requirements

• PHP 7.4 or newer, with the openssl extension (only needed if you store the secret key in the database rather than in wp-config.php).
• WordPress 6.0 or newer.
• Outbound HTTPS from your web server to the storage endpoint.

External services

This plugin is a client for third-party object storage. Its entire purpose is to transfer your media to a storage provider that you choose and configure. It does not contact any service until you enter your own storage credentials, and it never sends anything to the plugin author. There is no telemetry, tracking, or analytics of any kind.

Which service is contacted depends entirely on the provider you select on the Connection screen.

Amazon S3

Used only if you select «Amazon S3» as your provider. The plugin connects to the Amazon S3 REST API at your chosen region’s endpoint (for example, s3.eu-west-1.amazonaws.com) in order to store, read, verify and delete your media files.

What is sent, and when:

• Your media files (the original plus every generated image size) — when you run a bulk transfer, when a new file is uploaded and automatic offload is enabled, or when you offload a single attachment.
• Object names and file sizes — on every request, so the plugin can verify that what was stored matches what was on disk.
• Your AWS access key ID and a request signature derived from your secret key — on every request, as required by AWS Signature Version 4. Your secret key itself is never transmitted.
• A small test file — only when you press «Test connection». It is written, read back, and immediately deleted.
• Delete requests — when you delete an attachment in WordPress, or bring media back to local disk and choose to remove the remote copies.

Service provided by Amazon Web Services, Inc.
Terms: https://aws.amazon.com/service-terms/
Privacy policy: https://aws.amazon.com/privacy/

DigitalOcean Spaces

Used only if you select «DigitalOcean Spaces» as your provider. The plugin connects to the Spaces API at your chosen datacenter endpoint (for example, nyc3.digitaloceanspaces.com). The data sent, and the circumstances under which it is sent, are identical to the Amazon S3 list above, using your Spaces access key and signature.

Service provided by DigitalOcean, LLC.
Terms: https://www.digitalocean.com/legal/terms-of-service-agreement
Privacy policy: https://www.digitalocean.com/legal/privacy-policy

Other S3-compatible storage

If you select «Other S3-compatible» you supply the endpoint URL yourself, and the plugin talks only to that host. This is intended for providers such as Cloudflare R2, Wasabi, Backblaze B2, or a self-hosted MinIO server. The data sent is the same as above. Because you choose the host, you are responsible for reviewing that provider’s own terms and privacy policy.

Serving media

Once media is offloaded, the URLs on your site point at your storage bucket (or at a CDN hostname, if you configure one). Visitors» browsers therefore request those files directly from your chosen provider, and that provider will see the visitor’s IP address and user agent, as it would for any file hosted there.

Contact

Found a bug, or something behaved in a way this readme did not predict? Get in touch at https://AtlasGondal.com/contact-me/?utm_source=self&utm_medium=wp&utm_campaign=atlas-media-offloader&utm_term=plugin-description