All jobs

Add Page Caching to a Wagtail Site

Yes. An agent adds Django's cache middleware to your Wagtail site, skipping the admin, previews and signed-in editors, purges on publish, tests it, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the cache configuration that already exists before adding a layer on top of it, because Wagtail sites usually have a cache backend and no page caching. In a site shaped like wagtail/bakerydemo, requirements/base.txt pins Django>=6.0,<6.1 and wagtail>=8.0,<8.1, and requirements/production.txt adds django-redis. bakerydemo/settings/production.py defines CACHES with a default and a renditions alias on REDIS_URL when it is set, falling back to LocMemCache, and installs wagtail.contrib.frontend_cache with a Cloudflare backend only when the Cloudflare variables exist. settings/test.py forces LocMemCache. MIDDLEWARE in settings/base.py runs SecurityMiddleware, WhiteNoise, sessions, CommonMiddleware, CSRF, authentication, messages, clickjacking and Wagtail's RedirectMiddleware, and no cache middleware at all, so every anonymous request renders a page from the database.

Django's per-site cache is two middlewares that must bracket the others: UpdateCacheMiddleware first in the list and FetchFromCacheMiddleware last. Applied as-is to a Wagtail site they cache the admin, the preview panel and the editor's user bar, so the agent writes bakerydemo/base/middleware.py with a PageCacheMiddleware that subclasses both behaviours and skips any request whose path starts with /admin/, /django-admin/ or /documents/, any request with a session cookie or an authenticated user, anything but GET and HEAD, and any response that is not a 200. base.html renders {% wagtailuserbar %}, which only signed-in users see, so excluding authenticated requests keeps the anonymous HTML free of it. The agent sets CACHE_MIDDLEWARE_SECONDS to a short value and CACHE_MIDDLEWARE_KEY_PREFIX to the site name, both in base.py, so the test settings pick them up.

Caching needs invalidation. When an editor publishes, Wagtail sends page_published and page_unpublished; the agent connects handlers in bakerydemo/base/signals.py, registered from the app config's ready(), that clear the page's own URL and its parent's from the cache by deleting the keys Django's get_cache_key computes for a synthetic GET to those paths, which is how the per-site cache can be invalidated for one URL. Because BlogIndexPage and the other index pages list their children, the parent's URL is what changes when a post is published, which is why the parent is purged too. The handlers also purge the search page, whose results depend on every page.

bakerydemo/base/tests/ already holds test_home_page.py and test_seo.py built on WagtailPageTestCase with a setUpTestData that creates the tree and a Site. The agent adds test_caching.py in the same style: an anonymous GET to the home page twice, asserting the second response carries the cache's headers and that HomePage.objects is not queried on the second request through assertNumQueries; a request to /admin/login/ never cached; a signed-in client never cached; and a publish() on a child page followed by a request that renders fresh content. It runs ./manage.py check, ./manage.py makemigrations --check --noinput and ./manage.py test with DJANGO_SETTINGS_MODULE=bakerydemo.settings.test, exactly the three commands .github/workflows/ci.yml runs, then make lint-server for ruff and djhtml, and pastes the results in the pull request.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add page caching to this Wagtail site and open a pull request. Read requirements/base.txt, requirements/production.txt, bakerydemo/settings/base.py, bakerydemo/settings/production.py, bakerydemo/settings/test.py, bakerydemo/urls.py, bakerydemo/templates/base.html, bakerydemo/blog/models.py, bakerydemo/base/tests/test_seo.py, Makefile and .github/workflows/ci.yml first. Add bakerydemo/base/middleware.py with a PageCacheMiddleware built on Django's UpdateCacheMiddleware and FetchFromCacheMiddleware that skips paths under /admin/, /django-admin/ and /documents/, requests with a session cookie or an authenticated user, methods other than GET and HEAD, and non-200 responses; place it first and last in MIDDLEWARE in settings/base.py, and set CACHE_MIDDLEWARE_SECONDS to a short value and CACHE_MIDDLEWARE_KEY_PREFIX. Add bakerydemo/base/signals.py connected from the app config's ready() that, on page_published and page_unpublished, deletes the cache keys for the page's URL, its parent's URL and the search page. Add bakerydemo/base/tests/test_caching.py in the style of test_seo.py covering a cached second anonymous request, an uncached admin path, an uncached signed-in request and a fresh render after publish. Run ./manage.py check, ./manage.py makemigrations --check --noinput and ./manage.py test with the test settings, then make lint-server, and paste the output in the pull request. Do not change the templates, the models or the production cache backends.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request with bakerydemo/base/middleware.py, bakerydemo/base/signals.py, a ready() in the base app config, two entries and two settings in settings/base.py, and bakerydemo/base/tests/test_caching.py. The description shows the ./manage.py test summary, the makemigrations --check line proving no model changed, and the make lint-server output from ruff and djhtml.

The repository's workflow runs the same three management commands and both lint targets on every push and pull request, so a middleware import error, a test failure or a formatting slip fails there. Nothing in CI measures the cache, so the assertNumQueries test is the evidence that the second request skipped the database.

A reviewer checks that the admin and preview paths are excluded, that a signed-in editor never receives a cached page, that CACHE_MIDDLEWARE_SECONDS is short enough for their editorial pace, and that the publish handler purges the parent index as well as the page. Then they confirm REDIS_URL is set in production so the cache is shared across processes rather than per-worker LocMemCache.

Run it on every traffic spike or new site launch

A team running several Wagtail sites sends one POST /o/{org}/sessions per repository with this prompt and that repository in resources. Each run reads its own settings and middleware list, so a site already using wagtail.contrib.frontend_cache keeps it and gets only the server-side layer, and each opens its own pull request on its own branch.

Send a request_id with each body so a retried call returns the run already started. With a webhook_url on the API key, Rush POSTs run.completed when each turn ends, with the session_url to read the pull request from.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Page caching on a CMS fails in ways that look like success: the site is fast and an editor sees a stale page, or a visitor sees the user bar meant for staff. Those cases are only caught by requests made as different users against a running site, and in a Rush sandbox the agent makes them, through the test client as anonymous and signed-in users, with every command and assertion kept in the run's record.

The agent follows the project's own conventions, WagtailPageTestCase with setUpTestData and the three commands in ci.yml, so the pull request looks like the team wrote it. The same request body works unchanged on every Wagtail site a team runs, and several run at once in their own sandboxes.

Frequently asked questions

Will editors see stale pages?

No. Requests with a session cookie or an authenticated user bypass the cache, so anyone signed in to the admin always gets a fresh render, user bar included. Anonymous visitors see the cached page until page_published purges it or CACHE_MIDDLEWARE_SECONDS elapses.

What about the preview panel?

Previews are served to signed-in editors under /admin/, and both conditions skip the cache. base.html also sets <base target="_blank"> when request.in_preview_panel is true, which only ever renders for an uncached request.

Is this the same as wagtail.contrib.frontend_cache?

No. frontend_cache purges a CDN such as Cloudflare when a page is published; production.py enables it only when the Cloudflare variables are set. This change caches rendered pages inside Django using the CACHES backend already configured, and the two work together: the signal handler purges Django's cache while frontend_cache purges the edge.

Why purge the parent page too?

BlogIndexPage.get_context lists its live children ordered by date_published, and the other index pages do the same, so publishing a post changes the parent's HTML. The handler deletes the parent's cache key along with the page's own, and the search page's, because its results depend on every page.

Does it work with LocMemCache?

It works, but each process has its own memory, so a purge in one worker does not reach another. The test settings use LocMemCache on purpose; in production the pull request assumes REDIS_URL is set so django-redis serves one shared cache.

More Wagtail jobs

More jobs like this: Hand off a long task

Keep reading