Documentation
v2.0.37Two products, one optimization core. Pick the documentation that matches your deployment.
Out-of-process worker
ModPageSpeed 2.0 docs
The async worker behind an nginx reverse proxy, or ASP.NET Core middleware. Docker, configuration, deployment, and troubleshooting.
In-process module
mod_pagespeed 1.15 docs
The native module for Apache, nginx, and IIS. Install, the classic filter set, per-filter configuration, and the built-in admin console.
ModPageSpeed 2.0 documentation
Start here
Getting Started
Install ModPageSpeed 2.0. Two integrations share one optimization pipeline: a Docker / nginx reverse proxy, or ASP.NET Core middleware.
Install
Install with Docker
Run ModPageSpeed 2.0 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.
ModPageSpeed for nginx
ModPageSpeed 2.0 has no standalone nginx module yet. For a native nginx module today use mod_pagespeed 1.15; for 2.0 use the Docker / nginx reverse proxy.
Deploy with Helm
Install ModPageSpeed 2.0 on Kubernetes with the official Helm chart: a two-container sidecar pod, values reference, autoscaling, and upgrades.
Activate your license
Activate your ModPageSpeed 2.0 license key on nginx and the worker.
Configure
ModPageSpeed 2.0 configuration reference
Reference for ModPageSpeed 2.0 nginx directives, worker flags, and cache tuning. Looking for the mod_pagespeed 1.15 reference? See /1.1/docs/configuration/.
Set Cache-Control headers
Which Cache-Control headers to set on your origin, by content type and by framework, for correct caching with ModPageSpeed 2.0.
Choose a cache mode: safe vs aggressive
Control the Cache-Control headers ModPageSpeed 2.0 sets on optimized responses. Safe mode (default) adds must-revalidate for fast recovery; aggressive mode uses long TTLs with stale-if-error for cache efficiency.
Integrate with a CDN
Run ModPageSpeed behind Cloudflare, CloudFront, or Fastly: how Vary headers affect edge caching, per-CDN cache-key settings, and how to keep hit rates high.
Operate
Deploy ModPageSpeed 2.0 to production: Docker, Helm, systemd
Run the ModPageSpeed 2.0 worker and nginx 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 ModPageSpeed 2.0 web console at /console/.
Browser analysis with headless Chrome
How ModPageSpeed 2.0 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 ModPageSpeed 2.0 issues: cache misses, images not converting to WebP or AVIF, worker not processing, license warnings, 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 from your sitemap — a ModPageSpeed 2.0 capability, off by default and license-gated, with nothing leaving 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.
ASP.NET Core
Install ASP.NET Core middleware
Install ModPageSpeed as ASP.NET Core middleware via NuGet — the same 2.0 optimization pipeline (image transcoding, critical CSS) inside your .NET app, no nginx reverse proxy required.
Configure ASP.NET Core middleware
Configuration reference for the ModPageSpeed ASP.NET Core middleware: appsettings.json PageSpeed options, cache and worker settings, hot reload, environment variables, and common patterns.
Run in production
Production deployment guide for the ModPageSpeed 2.0 ASP.NET Core middleware: secret management, health probes, license enforcement, multi-instance scale, and zero-downtime restarts.
Reference
API Reference: IPC, Sockets, and C API
Reference for ModPageSpeed 2.0 internal interfaces: the nginx-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
ModPageSpeed 2.0 worker HTTP API reference: health, stats, Prometheus metrics, cache management, live config, and WebSocket streaming endpoints — all callable with curl.
Release Notes
ModPageSpeed 2.0 release notes — capabilities, performance, and security updates. Updating to the latest release is recommended.