# Upgrade

Upgrade mod_pagespeed 2.1 per shape: apt or dnf, Docker tag, Helm, the Windows installer and NuGet; what to read first, security updates, rollback.

Canonical URL: https://modpagespeed.com/docs/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](https://modpagespeed.com/docs/release-notes/#current-release).

## 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

```bash
# 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](https://modpagespeed.com/docs/installation-module/#nginx-compatibility) 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](https://modpagespeed.com/docs/cpanel/).

## 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:

```bash
# 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

```bash
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:

```bash
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](https://modpagespeed.com/docs/helm-deployment/) has the values.

## IIS

Download the current MSI from the [download page](https://modpagespeed.com/download/) 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:

```bash
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](https://modpagespeed.com/docs/release-notes/#security-updates) by impact class, with
"update recommended" and the affected versions. The standard signed packages
are free for everyone. A [support subscription](https://modpagespeed.com/support/) 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](https://modpagespeed.com/docs/uninstall/#roll-back-to-the-previous-release)
has the commands per shape.

## Frequently asked questions

**Do I upgrade the module and the optimizer worker separately?**

No. They are a matched pair: install, upgrade and roll them back together, and start the optimizer before the web server. On the packages the Apache module depends on the worker package at the same version, so one upgrade command moves both.

**How do security updates reach me?**

As regular releases through the channel you installed from, listed under Security in the release notes by impact class with "update recommended". A support subscription adds 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.