Upgrade

The current release is v2.2.0. Upgrading is a package, image or chart update on whichever shape you run, with one rule across all of them: the module and the optimizer worker move together, and the optimizer starts first. Read the current release’s notes before you start; the one-time steps a release needs are listed under “Before you upgrade” in the release notes.

Before you upgrade

• Read the release notes. A release that changes the cache format starts the cache empty once: the new optimizer opens a new volume beside the old one and never reads the old one, so the first requests after the upgrade are misses and the hit rate dips until the cache refills. The old files stay on disk, which is what makes a rollback warm; delete them once you will not roll back.
• Check free space. Both volumes exist during such an upgrade, so the cache directory needs free space at least equal to the configured cache size on top of what the current volume occupies.
• Pick a quiet hour if your origin is sensitive to the refill.
• Move both parts together, optimizer first. A module and an optimizer on different cache formats do not share a cache: the Apache module refuses to attach and says so; the native nginx module turns in-place optimization through the optimizer off and logs the reason; the reverse-proxy nginx keeps serving with its cache off and logs one error until the two agree. Starting the optimizer and then restarting the web server clears all three.

Apache and nginx packages

# Debian / Ubuntu
sudo apt-get update
sudo apt-get install --only-upgrade mod-pagespeed pagespeed-optimizer           # Apache
sudo apt-get install --only-upgrade nginx-module-pagespeed pagespeed-optimizer  # nginx

# AlmaLinux / RHEL / Rocky
sudo dnf upgrade mod-pagespeed pagespeed-optimizer            # Apache
sudo dnf upgrade nginx-module-pagespeed pagespeed-optimizer   # nginx

Upgrading or reinstalling the pagespeed-optimizer package turns the optimizer service back on and restarts it, even if you had turned it off. Then restart the web server: sudo systemctl restart apache2 (httpd on Enterprise Linux) or sudo systemctl restart nginx. At boot the packaged unit orders the optimizer ahead of apache2.service, httpd.service and nginx.service; during a hand-run upgrade that order is yours to keep: optimizer first, web server second.

The nginx module is built for the exact nginx version your distribution ships, and nginx refuses to load a module built for another version; see the compatibility table before you upgrade nginx itself.

On cPanel / EasyApache 4 the module is the ea-apache24-mod_pagespeed RPM in the opt-in ea4 repository: sudo dnf upgrade --enablerepo=ea4 ea-apache24-mod_pagespeed. See cPanel / EasyApache 4.

Docker

The worker and nginx images are tagged by release, and the two must run the same tag. Set it in deploy/.env and recreate the stack:

# deploy/.env
PAGESPEED_VERSION=2.2.0

docker compose -f deploy/docker-compose.yml pull
docker compose -f deploy/docker-compose.yml up -d

The named cache volume survives the recreate, and both containers share one PID namespace through the pidns container, so an upgrade that briefly mixes builds does not put the cache’s write lock at risk. The combined evaluation image is the one image published as :latest: docker pull ghcr.io/we-amp/pagespeed-combined:latest, then recreate its container.

Helm

helm repo update
helm upgrade pagespeed weamp/pagespeed -f my-values.yaml

Or move only the image tag. The chart takes one image.tag for both images (leave it unset to track the chart’s appVersion); the per-image worker.image.tag and nginx.image.tag keys are rejected, because a worker and an nginx on different builds break the async-CSS loader:

helm upgrade pagespeed weamp/pagespeed --reuse-values --set image.tag=2.2.0

The emptyDir cache is lost on pod restart and rebuilds as requests arrive. Deploy with Helm has the values.

IIS

Download the current MSI from the download page and run it over the existing install, then iisreset. An upgrade or repair keeps an optimizer service you turned on running and keeps the cache size you chose. The IIS package ships from the 1.15 packaging channel.

ASP.NET Core

Update the package reference and redeploy:

dotnet add package WeAmp.PageSpeed.AspNetCore

Without a version, dotnet add package pins the newest release in the project file. The middleware launches the worker from the same package, so the two stay matched by construction.

Security updates

Security fixes ship as regular releases through the channel you installed from, and every one is listed under Security in the release notes by impact class, with “update recommended” and the affected versions. The standard signed packages are free for everyone. A support subscription adds support from the people who build the product, with agreed response times and SLA-backed delivery of security updates; from the Priority tier up, hardened builds of the same code come through the subscriber repository ahead of the public release.

Roll back

Roll the module and the optimizer back together, optimizer first, to the previous release you ran. After a release that changed the cache format, the previous release’s cache files are still on disk, so the rollback starts with a warm cache (on nginx, only until you ran the one-time flush that release asked for). Uninstall and rollback has the commands per shape.