Skip to content
Lumber Mill

Uploads fallback

Locally you rarely need a full copy of the uploads folder. With the uploads fallback, DDEV serves an upload from disk when it exists and otherwise redirects the request to a remote site (usually production).

Setup

Section titled “Setup”

Add UPLOADS_FALLBACK_URL to web_environment in .ddev/config.yaml:

web_environment:
    - UPLOADS_FALLBACK_URL=https://www.example.com

Then restart DDEV:

Terminal window
ddev restart

To use a different URL on your machine only (e.g. staging), set it in .ddev/config.local.yaml instead. That file is not committed.

When UPLOADS_FALLBACK_URL is not set, the fallback is disabled and uploads are only served locally.

How it works

Section titled “How it works”

.ddev/web-entrypoint.d/uploads-fallback.sh runs on every ddev start/ddev restart and writes a webserver config inside the web container:

  • apache-fpm — a rewrite rule on web/app/uploads that redirects when the requested file does not exist.
  • nginx-fpm — a try_files on /app/uploads/ that falls back to a redirect.

Missing files get a 302 to UPLOADS_FALLBACK_URL plus the original path, so /app/uploads/2024/01/photo.jpg redirects to https://www.example.com/app/uploads/2024/01/photo.jpg.