Documentation

Install with Docker

Run mod_pagespeed 2.1 in Docker with Docker Compose: the nginx module, the worker, and a shared Cyclone cache. A one-container quick try, then a three-service production stack.

Install the nginx module

Install the native mod_pagespeed 2.1 module for Apache and nginx from the signed packages.modpagespeed.com repository, or run the Docker / nginx reverse proxy.

cPanel / EasyApache 4

Install, uninstall, and maintain mod_pagespeed on cPanel / EasyApache 4: the signed EA4 RPM, enabling it in WHM Customize, the cpanel/elevate OS-upgrade runbook, and how the Apache Module Magic Number keeps routine ea-apache24 updates from breaking the module.

Deploy with Helm

Install mod_pagespeed 2.1 on Kubernetes with the official Helm chart: a two-container pod (module + optimizer worker), values reference, autoscaling, and upgrades.

License

mod_pagespeed 2.1 is licensed under the Apache License 2.0; what is sold is support subscriptions and hardened builds.

Migrating from ModPageSpeed 2.0 to mod_pagespeed 2.1

What changes when you move a ModPageSpeed 2.0, mod_pagespeed 1.15, or open-source mod_pagespeed deployment to mod_pagespeed 2.1: your configuration carries over, the worker runs unprivileged, and the management API and browser sandbox get strict defaults.

Configuration reference

Reference for mod_pagespeed 2.1: nginx and Apache directives, optimizer-worker flags, and cache tuning, plus the native module directive reference.

Set Cache-Control headers

Which Cache-Control headers to set on your origin, by content type and by framework, for correct caching with mod_pagespeed 2.1.

Choose a cache mode: safe vs aggressive

Control the Cache-Control headers mod_pagespeed 2.1 sets on optimized responses — safe mode (default) adds must-revalidate for fast recovery, aggressive mode uses long TTLs with stale-if-error — plus the in-process module cache reference: Cyclone storage, memcached and Redis, purging, sizing and IPRO.

Integrate with a CDN

Run mod_pagespeed 2.1 behind Cloudflare, CloudFront, or Fastly: how Vary headers affect edge caching, per-CDN cache-key settings, and how to keep hit rates high.

Domain Configuration

Authorize and map domains in mod_pagespeed 2.1 on nginx, Apache, and IIS. Reference for the Domain, MapOriginDomain, MapRewriteDomain, MapProxyDomain, ShardDomain, and LoadFromFile directives.

HTTPS Configuration

Fetch HTTPS resources in mod_pagespeed 2.1 on nginx, Apache, and IIS: FetchHttps with SSL certificate verification, MapOriginDomain to an HTTP backend, or LoadFromFile.

IIS Configuration

Configure mod_pagespeed on IIS via pagespeed.config — the native IIS module and successor to IISpeed. Directive syntax, path-based regex matching, server and site-level config, and environment-variable expansion.

Deploy to production: Docker, Helm, systemd

Run the optimizer worker and the module in production with Docker Compose, Kubernetes (Helm), or systemd — covering file permissions, logging, monitoring, and cache sizing.

Use the web console

Inspect cache contents, monitor live throughput and bandwidth savings, and hot-reload configuration from the mod_pagespeed 2.1 web console at /console/.

Browser analysis with headless Chrome

How the optimizer worker renders pages in headless Chrome to extract critical CSS, detect the LCP element, measure JavaScript coverage, and gate optimizations against visual regressions.

Troubleshoot common issues

Fix common mod_pagespeed 2.1 issues: cache misses, images not converting to WebP or AVIF, the optimizer worker not processing, and socket diagnostics.

Serve Markdown to AI agents

Serve AI agents a rendered Markdown copy of your pages at the same URL, and synthesize an /llms.txt — off by default, nothing leaves your server.

Verify AI crawlers with Web Bot Auth

Check RFC 9421 signatures from AI crawlers at your origin and label each request with a verified bot identity — observe-only, off by default.

Validate RSL license capability tokens

Validate Authorization: License capability tokens at your origin and return 401/402/pass — experimental operator access control, off by default.

mod_pagespeed Admin Console

mod_pagespeed 2.1 admin console: statistics, cache inspection, message history, and config. Setup and access control for nginx, Apache, and IIS at /pagespeed_admin/.

Security

Security guidance for mod_pagespeed 2.1: restricting admin pages, domain authorization, untrusted content, CSS/XSS, cache poisoning, HTTPS, and CVE patching.

Filters Overview

The complete mod_pagespeed 2.1 filter set, grouped by category — image, CSS, JavaScript, HTML, and caching filters — with what each one does and how to enable it.

Filter Selection

Choose which mod_pagespeed 2.1 filters to run: RewriteLevel presets, the CoreFilters default set, EnableFilters, DisableFilters, ForbidFilters, and tuning thresholds.

PageSpeed Filter Reference

Every PageSpeed filter in mod_pagespeed 2.1 — all 66, with category, CoreFilters and OptimizeForBandwidth status, a safety rating, and a one-line description. nginx, Apache, and IIS syntax included.

Image Filters

Configure image optimization filters in mod_pagespeed 2.1 for Apache, nginx, and IIS: recompression, WebP and opt-in AVIF conversion, resizing, lazy loading, and responsive images.

CSS Filters

Reference for CSS optimization filters in mod_pagespeed 2.1: minify, combine, inline, and flatten @import CSS, plus critical-CSS extraction. Apache, nginx, and IIS syntax with tuning parameters.

JavaScript Filters

Minify, combine, inline, and defer JavaScript in mod_pagespeed 2.1. Directives, defaults, and the trade-offs for each JS filter on Apache, nginx, and IIS.

HTML Filters

HTML optimization filters in mod_pagespeed 2.1: collapse whitespace, strip comments, elide attributes, DNS prefetch, and resource preload hints.

Install ASP.NET Core middleware

Install the mod_pagespeed 2.1 ASP.NET Core middleware via NuGet — the same optimization pipeline (image transcoding, critical CSS) inside your .NET app.

Configure ASP.NET Core middleware

Configuration reference for the mod_pagespeed 2.1 ASP.NET Core middleware: appsettings.json PageSpeed options, cache and worker settings, and hot reload.

Run in production

Production deployment guide for the mod_pagespeed 2.1 ASP.NET Core middleware: configuration, health probes, multi-instance scale, and zero-downtime restarts.

API Reference: IPC, Sockets, and C API

Reference for mod_pagespeed 2.1 internal interfaces: the module-to-worker IPC wire format, the health and management sockets (STATS, PURGE, METRICS), the capability-mask encoding, and the ps_ C API.

Call the worker HTTP API

Optimizer worker HTTP API reference for mod_pagespeed 2.1: health, stats, Prometheus metrics, cache management, live config, and WebSocket streaming endpoints — all callable with curl.

Where the Documentation Lives

Where the mod_pagespeed 2.1 documentation lives, and what happened to the pages written before the 2.0 re-architecture converged into it.

Release Notes

mod_pagespeed 2.1 release notes — every release of the module and the optimizer worker, with security updates and what has changed since the last upstream release.

mod_pagespeed Directive Index (Apache & nginx)

Alphabetical reference of every mod_pagespeed 2.1 configuration directive — Apache and nginx syntax, default values, and links to the full caching, image, CSS/JS, and domain docs.

PageSpeed filters reference

The image, CSS, JavaScript, HTML, and caching filters, what each one does, and which run by default.

Release notes

How it works

CSS parsing, the metadata cache, and optimizing off the request path — the mechanics under the filters.