Skip to content

CMS Images

Using editor-uploaded images in templates

Images may be uploaded into Wagtail's Image library and then included in content-managed surfaces that have fields/spaces for images.

CMS-uploaded images are stored in the same media bucket that stored-in-repo/hard-coded images get put in, and coexist alongside them, being namespaced into a directory called custom-media/.

If a surface uses an image, images use must be made explicit via template markup --- we need to state both where and how an image will be used in the template, including specifying the size the image will be. This is because --- by design and by default --- Wagtail can generate any size version that the template mentions by providing a "filter spec" e.g.

{% set the_image=image(page.product_image, "width-1200") %}
<img class="some-class" src="{{ the_image.url }})"/>

(More examples are available in the Wagtail Images docs.)

Allowed filter specs

When including an image in a template we ONLY use filter specs between 2400px down to 200px in 200px steps, plus 100px.

Laying them out, these are the only filter specs allowed. Using alternative ones will trigger an error in production.

  • width-100
  • width-200
  • width-400
  • width-600
  • width-800
  • width-1000
  • width-1200
  • width-1400
  • width-1600
  • width-1800
  • width-2000
  • width-2200
  • width-2400

Why are we limiting filter-specs to that set?

In a line: to balance infrastructure security constraints with site flexiblity, we have to pre-generate a known set of renditions.

Normally, if that product_image is not already available in 1024x1024, Wagtail will resize the original image to suit, on the fly, and store this "rendition" (a resized version, basically) in the cloud bucket. It will also add a reference to the database so that Wagtail knows that the rendition already exists.

In production, the "Web" deployment has read-only access to the DB and to the cloud storage, so it will not be able to generate new renditions on the fly. Instead, we pre-generate those renditions when the image is saved.

This approach will not be a problem if we stick to image filter-specs from the 'approved' list. Note that extending the list of filter-specs is possible, if we need to.

I've downloaded a fresh DB and the images are missing

That's expected: the images don't live in the DB, only references to them live there. CMS images are destined for public consumption, and Dev, Stage and Prod all store their images in a publicly-accessible cloud bucket.

We have a tool to help you sync down the images from the relevant bucket.

By default, the sqlite DB you can download to run Bedrock or Springfield locally is based on the data in Bedrock Dev or Springfield Dev. To get images from the cloud bucket for dev, run:

./manage.py download_media_to_local

This will look at your local DB, find the image files that it says should be available locally, copy them down to your local machine, then trigger the versions/renditions of them that should also exist.

The command will only download images you don't already have locally. You can use the --redownload option to force a redownload of all images.

If you have a DB from Stage you can pass the --environment=stage option to get the images from the Stage bucket instead. Same goes for Production.