DoD.ist Media
Serve WordPress images through the img.dod.ist image transformer and warm its cache for media that already exists.
Description
DoD.ist Media rewrites WordPress image URLs to the img.dod.ist transformer and fills the transformer cache for a library that was uploaded before the switch. It never uploads, moves or deletes files, and it only writes its own options and queue table.
Two URL shapes are produced:
- Base URL, no query:
https://img.dod.ist/<tenant>/<path>. Returned bywp_get_attachment_url()and bydodist_image_url( $id ). A raw attachment link uses the app's default quality. - Sized URL: the base plus
?w=<width>&q=<quality>. Returned bywp_get_attachment_image_src(),srcset,dodist_image_url( $id, $w, $q )and for thesrcof images embedded in post content.qis explicit on every sized URL and defaults to 75.
The image format is negotiated by the request Accept header (image/avif vs WebP). No format, timestamp or resize parameters are ever added to the URL, so page caches and CDNs keep working.
Delivery has three modes. Off leaves every URL local. Preview shows transform URLs to logged-in administrators only. On serves the front end and REST from the transformer while wp-admin screens stay local. Go-live requires 95 % of eligible images to have both required formats complete and the scan to be finished, unless an administrator explicitly overrides the gate.
Warm-up builds the lossless file plus one full-size WebP and one full-size AVIF per raster image, at the attachment's main-file width, with one quality per run. srcset widths are not warmed; the app generates them lazily on first view, which keeps the warm-up predictable.
Safety rules built in:
- Cropped sizes, unsupported mime types and duplicate basenames are skipped and stay on the origin.
- SVG, PDF, DOC, DOCX and XLSX images get the base URL only: no
w, noq, nosrcset, and no warm-up request. - One runner and one request at a time, guarded by an option lock.
- A night window, a per-request delay, a rate limit and a daily budget bound every run. Pause and the window are respected by background runs too.
- Failures are retried a bounded number of times, and repeated failures pause the run instead of hammering the app.
WP-CLI is the primary warm-up runner; the admin screen can also run it from the browser, and WP-Cron continues a started run in the background.
The companion transformer app, its tenant configuration and its cache are a separate project.
Installation
Two steps: get the plugin onto the site, then point it at a transformer tenant. Pick one way to get the files and stay with it - the plugin's own update checker and Composer would otherwise both manage wp-content/plugins/wp-dodist-media.
From wp.dod.ist
Every version is listed at https://wp.dod.ist, and the newest one is always at
https://wp.dod.ist/wp-dodist-media/download/
Add ?<version> to that URL - for example https://wp.dod.ist/wp-dodist-media/download/?0.1.7 - to pin a release, which is what you want if the same site must be reproducible later.
- wp-admin: Plugins → Add New → Upload Plugin, pick the zip, install.
- WP-CLI:
wp plugin install "https://wp.dod.ist/wp-dodist-media/download/" --force - Manually: unpack the zip into
wp-content/plugins/. It holds onewp-dodist-media/folder and no development files.
Installed this way the dashboard shows plugin updates. The plugin asks https://wp.dod.ist/wp-dodist-media/check every 12 hours and downloads a new version from the same host; the request carries the version it runs, nothing else.
With Composer
For a site that already installs plugins with Composer. The package is dodist/wp-dodist-media (type wordpress-plugin) in the repository at https://wp.dod.ist/packages/, and it is the same zip the dashboard downloads.
{
"repositories": [
{ "type": "composer", "url": "https://wp.dod.ist/packages/" }
],
"require": {
"composer/installers": "^2.3",
"dodist/wp-dodist-media": "^0.1"
},
"config": {
"allow-plugins": { "composer/installers": true }
},
"extra": {
"installer-paths": {
"wp-content/plugins/{$name}/": ["type:wordpress-plugin"]
}
}
}
composer update dodist/wp-dodist-media
allow-pluginsis not optional. Composer 2 refuses to run any installer until it is allowed, and stops with "composer/installers ... is exception (false)" without that block.{$name}is the package slug, so the plugin lands inwp-content/plugins/wp-dodist-media/with its header at the folder root - Composer unwraps the zip's single top-level directory.- Commit
composer.jsonandcomposer.lock, then update withcomposer update dodist/wp-dodist-media. On a Composer-managed site ignore the dashboard prompt, or the two will fight over the same directory. - Only released versions are published, so a Composer install always matches a downloadable zip.
Configure
- Prepare the transformer app for this site: a tenant with a bucket root and the site hosts, pointing at this site's uploads. Note the tenant key and the uploads layout.
- Activate the plugin. Activation creates the queue table; nothing is rewritten and no warm-up starts until the plugin is configured.
- Open DoD.ist in wp-admin and fill in:
- Base URL: the transform host, for example
https://img.dod.ist. HTTPS only, exceptdod.ist.internalorlocalhostwhenDODIST_MEDIA_DEVis defined. - Tenant: the key in the app config. Never leave it empty to change the URL shape - use the checkbox below.
- Append the tenant to the URL path: leave it on for
img.dod.ist, and turn it off only when the Base URL is the site's own media subdomain, which the app must allow for the tenant. The plugin asks the app when you save and says so when the answer is no. - Source prefix: the path prepended to attachment paths. Bucket roots differ per site, so set this per site.
- Quality: 1-100. Leave it at 75 until the app proves it keys its cache by quality by sending
X-Dodist-Quality-Keyed: 1(see the FAQ). - Formats: WebP and/or AVIF. Keep at least one checked.
- Base URL: the transform host, for example
- Use Test newest image on the same screen and fix the source prefix until the exact URL returns 200 /
image/*. The test also reports whether the app keys its cache by quality. - Click Build queue (or run
wp dodist scan). This only fills the queue; it never starts a request by itself. - Warm with WP-CLI, which is the fastest and safest option:
wp dodist warm --max=100 --seconds=600
Or press Start in wp-admin for a slow, one-request-per-tick run. Watch the complete / WebP / AVIF counters until they reach the gate.
Warm-up respects the night window (default 01:00-06:00). The Warm-up section shows it with the server time and whether it is holding the run; change it under Delivery → Warm-up window, leave both fields empty to warm at any time, or run the CLI once with --force. logged-in administrator, and finally go live.
Optional constants in wp-config.php override the stored settings:
DODIST_MEDIA_BASE_URLDODIST_MEDIA_TENANTDODIST_MEDIA_DELIVERY(off,preview,on)DODIST_MEDIA_QUALITYDODIST_MEDIA_DEV(allows an HTTP base URL fordod.ist.internal/localhost)DODIST_MEDIA_PURGE_TOKEN(enables purging; see below)DODIST_MEDIA_API_TOKEN(read-only, letswp dodist purge --orphanslist the cache)
If the tenant is not set in the settings or by constant, the plugin falls back to the LAADA_DOD_IST_USER constant.
The transform host must be allowed by your Content Security Policy, for example img-src 'self' https://img.dod.ist data:.
WP-CLI
wp dodist status [--format=table|json]
wp dodist config [--base-url=<url>] [--tenant=<tenant>] [--tenant-in-url=<0|1>] [--source-prefix=<path>] [--quality=<1-100>] [--formats=webp,avif] [--delivery=off|preview|on]
wp dodist scan [--dry-run] [--force]
wp dodist warm [--formats=webp,avif] [--max=<requests>] [--seconds=<seconds>] [--rate=<requests/min>] [--force] [--yes]
wp dodist reset [--failures]
wp dodist test [--width=<px>] [--quality=<1-100>] [--format=webp|avif] [--referer]
wp dodist purge <id>... [--send]
wp dodist purge --status
wp dodist purge --orphans [--dry-run]
wp dodist limits [--format=table|json]
wp dodist subdomain <host> [--check|--verify]
wp dodist warm exits 0 when the queue is done, 1 on error, and 2 when it stopped because of a pause, the window, the daily budget or a lock.
Can I install it with Composer?
Yes, if the site already installs WordPress plugins that way: dodist/wp-dodist-media is published with the wordpress-plugin type, so composer/installers puts it in wp-content/plugins/wp-dodist-media/. The full composer.json block, the allow-plugins requirement and the update workflow are in Installation → With Composer. Mixing the two - a Composer install and the dashboard prompt - is what breaks, because both write to the same directory.
Why is q always 75 on sized URLs?
The transformer app has to include the quality in its cache key (in the derivative filename) before a variable q is safe: otherwise ?w=1200&q=60 and ?w=1200&q=90 share one cached file. Until the app answers a served image with X-Dodist-Quality-Keyed: 1, the plugin sends the app's default quality (75) on sized URLs and in warm-up, and says so on the DoD.ist screen. Varying q before that would mix cache entries.
A contract claiming quality_keyed is not enough. The claim is recorded separately and shown as quality_keyed_claimed; only the header proves it, and the header is only seen by the connection test and by a real warm request. Once proven, the configured quality is used and the proof survives settings saves and contract refreshes. It is lost only if the app stops sending the header — for example after an app rollback — which puts the plugin back on 75. The connection test reports the current app capability and is cached for an hour.
Can the plugin restore a missing original?
Not from its derivatives: the lossless WebP and the AVIF are re-encodings of the decoded pixels, so the original bytes, container and metadata are gone. The bucket is the archive, and wp dodist restore copies from it deliberately:
wp dodist restore # where the originals are, and what is missing
wp dodist restore 123 --dry-run
wp dodist restore 123 --yes
Restoring one file at a time, it refuses to overwrite an existing file, and it verifies the downloaded bytes against the hash the app reported when the image was warmed (stored as _dodist_origin on the attachment). A mismatch aborts and keeps the download for inspection. Nothing is restored automatically, ever — not on a page load, not during a warm-up.
An image warmed before the app started reporting that hash has no record yet, so run the connection test on it once (wp dodist test <id>), which records it, or re-warm it. Without a record the plugin says "cannot verify" instead of writing unverified bytes.
Does the plugin touch my uploads or the database?
No uploads are moved or deleted, except by wp dodist restore, which only ever writes a file that is missing and verifies it first. The only table is {prefix}dodist_warmup, which holds one row per planned request; uninstalling removes it together with the plugin's options, log, transients, scheduled event and the per-user notice state.
My uploads live in a bucket, not on the server. Does that work?
Yes. Paths, widths and mime types come from the attachment records, and every request goes to the transformer, which fetches the original from the tenant's bucket. Scanning and warming a bucket-only library works unchanged.
What does not work on such a site is leaving Delivery on *Off*: nothing rewrites the URLs, so they point at local files that do not exist. Switch to Preview or On first, then remove the old offload plugin or theme code — never run both at once. The plugin warns in wp-admin when it sees a library with no local originals while delivery is off.
Why are srcset widths not warmed?
Warming every width would multiply the request count and the AVIF cost for little benefit. Warm-up builds the full-size file per format; the app renders narrower widths on first view and caches them.
I get 404 for the test URL.
The app cannot find the source object. Check the tenant's bucket root and the Source prefix for this site; the test shows the exact URL it requested.
I get 403 during a warm-up.
Something in front of the app is rejecting the request: a WAF rule, hotlink protection or a bot filter (the warm-up identifies itself with X-Dodist-Warm: 1). A 403 pauses the run instead of retrying; fix the rule, then press Resume.
I get 502.
The app or its upstream (object storage, image library) failed. The row is retried a bounded number of times, then marked failed; after repeated failures the run pauses. Check the app logs, then use Retry failures.
Another site is showing my images. How do I stop it?
The app refuses a request whose Referer names a host the tenant does not list, so an image embedded on another site's page - or served through a proxy in front of another name - answers 403 referer_refused instead of the image. Make sure every host your site serves pages from is in the tenant's hosts on the app (www as well as the bare domain if both serve), because a listing you are missing breaks your own pages, not someone else's.
The one hole left is a request with no Referer at all: a hotlinker can drop the header on purpose. Turning on the tenant's "refuse a request that carries no Referer" closes it, and also refuses direct links, visitors whose browser or extension strips the header, and the warm-up runner unless you also set a warm-up Referer (warmup_referer plus wp dodist warm --referer). It is off by default for that reason.
Can my media be served from my own subdomain?
Yes, and the app decides which hostname you may use. DoD.ist → Media subdomain walks the four steps: allow the hostname on the app, generate the file, point the subdomain at this host, then check it works.
wp dodist subdomain media.example.com # the .htaccess
wp dodist subdomain media.example.com --check # only: is the hostname allowed?
wp dodist subdomain media.example.com --verify # only: does it actually serve?
Generating asks the app, and only when the app says the hostname is allowed for the tenant do you get the file. A hostname the app does not allow produces a refusal and nothing else: the file is setup help, not a permission. The DNS record, the certificate and the subdomain's hosting stay yours to set up.
Checking is the step that tells you it worked. The plugin fetches one image through the app, the same image through the subdomain - with this site's own Referer, so the tenant's hosts list is exercised too - and compares the bytes. You get a line per check: the app answered, the subdomain answered, it is an image, the app produced it (X-Dodist-* headers), and the bytes match. A subdomain that answers an HTML 404, or a proxy that re-encodes, fails the line that names it.
Serving the subdomain straight from the app instead of through that file needs no .htaccess at all - point the subdomain at the app and list it for the tenant; the same check proves it.
To get the short URL, three settings, and the tenant stays filled in:
base_url https://media.example.com
tenant example (always required: it is the identity)
tenant_in_url off (the checkbox "Append the tenant to the URL path")
That is the only thing the checkbox changes. Emptying the Tenant field instead does not switch URL shapes, it turns the plugin off: every URL is unbuilt, delivery goes inert and the warm-up refuses, because the tenant is what names the contract, the cache key, the purge route and the warm-up request. Use the checkbox.
The plugin checks the host when you save: if the app does not allow it for the tenant, the screen says the URLs would answer 404 rather than letting a site fill up with broken images.
Which images are skipped?
Cropped sizes (a different aspect ratio), unsupported mime types, and files whose basename appears more than once in the library. Skipped files keep their local URLs; wp dodist scan --dry-run reports how many duplicate basenames it found.
Does switching delivery off again revert everything?
It stops new URLs from being rewritten, but HTML, browser and CDN caches that already contain transform URLs keep serving them until they are purged. Purge page caches after any delivery change.
How do I call the transformer from a theme or a headless API?
Use dodist_image_url( $id ) for the base URL, or dodist_image_url( $id, $width ) for a sized URL; pass $quality only when you deliberately want a value other than the default. It returns null when the plugin is not configured or the attachment is not eligible. If your theme builds its own srcset, build each candidate with dodist_image_url( $id, $width ) instead of appending ?w= to the base URL, otherwise those URLs lose the explicit q. Note that this helper deliberately ignores the Delivery setting: API authors who call it opt out of the delivery gate and are responsible for only returning transform URLs once the corresponding images are warm.
How do I stop everything?
Pause on the DoD.ist screen stops further requests and clears the scheduled event. wp dodist reset deletes the queued rows (wp dodist reset --failures only requeues failed ones), and deactivating the plugin also clears the event and releases the lock.
Why does the plugin warn about year/month folders?
The plugin compares the path layout your library actually uses with the one your tenant serves, because they can disagree:
- WordPress stores uploads as
2025/11/photo.jpgunless *Settings → Media → Organize my uploads into month- and year-based folders* is turned off. - A flat bucket or a flat offload stores
photo.jpg.
When the library is nested but the tenant serves flat paths, every media URL returns 404 and warm-up is blocked with an error telling you so — that is the one case that has to be fixed before anything else. When the library is flat but the tenant is declared nested, media URLs still work, so you get a warning instead. A mixed library (some nested, some flat) usually means a migration or a second offload plugin is still running, and also warns, without blocking.
wp dodist status always shows all four values:
layout_wp_yearmonth on | off
layout_detected nested | flat | mixed | unknown
layout_tenant nested | flat | unknown
layout_state ok | info | warning | error
Use wp dodist status --refresh after changing the tenant in the app; that re-reads the contract (/<tenant>/contract) and re-samples the library. The plugin never rewrites a path or strips a prefix — flattening belongs to your own offload or mu-plugin.
Why was my upload rejected?
Uploads are checked before they are stored, against the ceilings the transformer app reports for your tenant:
- Format — jpg, jpeg, png, webp and gif are accepted. AVIF is not: the transformer produces AVIF, it does not accept it as an input. Existing AVIF attachments are left alone.
- Size — a per-image byte cap and a megapixel cap.
- Inefficiency — a bytes-per-pixel ceiling, so a file that is under the caps but badly encoded is still refused. Re-export it smaller or at a lower quality.
SVG/PDF/DOC/DOCX/XLSX are passthrough: no pixels, no ceilings. The file is not written when it is rejected, and the reason appears in the media screen's own upload error. Check the numbers with wp dodist limits, and see which existing attachments would fail today (they are reported, never deleted).
Note what tightening a ceiling does to files you already have: the plugin never deletes them, but the transformer applies the same ceilings when it is asked for a derivative, so an over-limit original starts answering 413 instead of being processed. Loosen the ceiling or replace the file if it needs to keep serving.
The ceilings come from the app and are cached, so they keep working when it is unreachable; DODIST_MEDIA_MAX_MEGAPIXELS, DODIST_MEDIA_MAX_BYTES, DODIST_MEDIA_MAX_BYTES_PER_PIXEL and DODIST_MEDIA_MAX_LIBRARY_IMAGES pin them from wp-config.php when you need to.
Why is warm-up blocked with "library is larger than the tenant allows"?
Installing the plugin on a site that already has a big media library is a different proposition from warming a fresh one: the first run spends real CPU on somebody else's existing archive. So the app carries a threshold (max_library_images) and a per-tenant approval (late_install_approved). Above the threshold and unapproved, delivery stays off and warm-up refuses to start.
It is fail-closed on purpose: an unreachable app, or an app too old to report the setting, keeps the gate closed rather than assuming approval. To clear it, approve the tenant in the app and run wp dodist status --refresh. Purging, and URLs that already work, are unaffected.
How do I delete an image's cached files on img.dod.ist?
Deleting or replacing an image in WordPress queues a purge automatically once DODIST_MEDIA_PURGE_TOKEN is defined. Until then nothing is queued and everything else works as before; the DoD.ist screen says the token is missing.
A purge removes the cached files for one image — every width and both formats — and never the original in your uploads folder or bucket. It is queued, sent by the runner one image per request, retried with backoff, and it never blocks or fails the delete in WordPress. You can also purge by hand:
wp dodist purge 123
wp dodist purge 123 --send
wp dodist purge --status
There is deliberately no tenant-wide purge in the plugin: no --all, no --older-than. Orphan cache entries (an object whose attachment no longer exists) are handled one file at a time:
wp dodist purge --orphans --dry-run
wp dodist purge --orphans
Purging the origin does not help a CDN or a browser that already holds the old bytes with max-age=31536000; the cache for a replaced image only becomes correct for those clients once the edge is purged too.
Screenshots
- The DoD.ist screen: coverage counters, connection test and delivery gate.
- The warm-up section with progress, ETA and the WP-CLI hint.
- The failures table with the exact URL, HTTP code and error.
Changelog
See CHANGELOG.md in the plugin folder for the full list. 0.1.0 was published as a packaging test on 2026-11-18 and superseded by 0.1.1 the same day, before anything installed it.
0.1.7
- The subdomain check printed the same URL twice once the Base URL was the subdomain itself. It reports one URL and says why.
0.1.6
wp dodist config --tenant-in-url=0was rejected as an unknown flag: the docblock did not declare it, and WP-CLI validates flags before the command runs. It is declared now, with an example.
0.1.5
- The tenant is no longer the URL shape. A new Append the tenant to the URL path checkbox (setting
tenant_in_url, on by default) decides betweenbase_url/tenant/photo.jpgandmedia.example.com/photo.jpg, while the Tenant setting stays required as the identity the app, the cache key, the purge route and the warm-up use. Emptying the Tenant to get a short URL used to switch the whole plugin off; it no longer needs to be touched.wp dodist config --tenant-in-url=0, andwp dodist statusreports the shape. - Saving asks the app whether the host the URLs are built on is allowed for the tenant (as soon as the tenant is left out of the path, or the Base URL changes), and the screen says the URLs would answer 404 when it is not.
- Removing the tenant from the path leaves every app route intact: the contract, purge, the media API and the subdomain check all still answer for the tenant segment on a vanity host.
0.1.4
- Media subdomain help is now a four-step flow on the DoD.ist screen, and it ends with a check: Check it works fetches one image through the app and the same image through the subdomain (carrying this site's own
Referer, so the tenant'shostslist is exercised) and compares the bytes, with a line per check. A subdomain answering an HTML 404, a proxy that re-encodes, and an app that refuses the site's Referer each fail the line that names them.wp dodist subdomain <host> --verifydoes the same from the console. - The hostname being set up is remembered, so the check can be re-run without retyping it.
- The generated
.htaccessends with its rules - the closing note is gone.
0.1.3
- Media subdomain setup help: DoD.ist → Media subdomain, or
wp dodist subdomain <host> [--check], asks the app whether the hostname is allowed for this tenant and only then prints the proxy.htaccesswith the tenant and app host baked in. A hostname the app does not allow, an unreachable app, or an app without the route produces a refusal and no file. The app remains the only place an allowance is granted. - The hotlink refusal now names itself (
403 referer_refused) before anything is fetched or cached, instead of a bare 403 from the renderer, and matching aRefererhost against the tenant'shostsis exact and case-insensitive - a subdomain of a listed host, or a domain that merely starts with it, is not served. An emptyRefererheader counts as no Referer. - New FAQ entries: how the media is kept off other sites, and how a subdomain is set up.
0.1.2
- Installation is split into "get the files" and "configure", with the two supported ways to get them: the zip from wp.dod.ist (upload, WP-CLI or manual) and Composer (
dodist/wp-dodist-mediafrom https://wp.dod.ist/packages/), including theallow-pluginsblock Composer 2 requires and a note not to mix the two. Documentation only - no code changes.
0.1.1
- Origin record and restore: the app reports the sha256 of each original on the first warm request, the plugin records it per attachment, and
wp dodist restoreputs a missing original back from the bucket - one file at a time, verified against the recorded size and hash, never over an existing file. A dry run and a REST route with the same capability check. - The warm-up window is shown with the server time and is editable on the settings screen; leaving it empty warms at any time. The CLI keeps
--force. - "Build queue" rebuilds the manifest when nothing is queued, instead of scanning nothing and saying nothing.
- The name is written DoD.ist throughout; slug, text domain and URLs are unchanged.
0.1.0
- First release: base/sized URL rewriting for attachment URLs,
src,srcsetand REST image sizes; passthrough URLs for SVG/PDF/DOC/DOCX/XLSX. - Manifest, queue, lock, logged runner with retry/pause, WP-CLI commands and a REST API for the admin loop.
- Admin screen with coverage stats, connection test, delivery gate with override, failures and log.
- Single WP-Cron event that continues a started warm-up.
- Purge: queued, per-image cache deletion on delete, replace and metadata regeneration;
wp dodist purge, a per-row and bulk action in the media library, an orphan sweep and a purge section on the DoD.ist screen. - Path layout detection: the plugin compares the observed upload layout with the tenant's declared one, warns on a mismatch, blocks warm-up when it would break every URL, and reports all four values in
wp dodist status(now with--refresh). - Upload guard: format, byte, megapixel and bytes-per-pixel checks on the temporary file before it is stored, using the ceilings the app reports. AVIF is refused as an input with an explanation; documents are untouched.
- Late-install gate: a library above the tenant's threshold stays un-warmed and off until the tenant is approved in the app. Fail-closed.
wp dodist limitsshows the ceilings, the gate state and any existing attachment that would fail.
Upgrade Notice
0.1.7
The subdomain check shows one URL when the Base URL is that subdomain.
0.1.6
wp dodist config --tenant-in-url works instead of being rejected as an unknown flag.
0.1.5
A checkbox decides the URL shape, so a short subdomain URL no longer needs the tenant to be emptied out of the settings.
0.1.4
A four-step media subdomain flow that ends by proving the subdomain serves the media.
0.1.3
Media subdomain setup help, asked of the app, plus a named hotlink refusal.
0.1.2
Documentation only: how to install from wp.dod.ist or with Composer.
0.1.1
First release, including origin restore and the editable warm-up window.
0.1.0
Packaging test, superseded the same day. Do not install.