Deprecated
The ngx_pagespeed module has been deprecated and removed from all Centmin Mod branches (132.00stable, 140.00beta01, 141.00beta01). The NGINX_PAGESPEED='y' variable no longer works. The documentation below is retained for historical reference only.
Overview
What is ngx_pagespeed?
ngx_pagespeed is Google's open-source Nginx module that automatically applies web performance best practices to pages and associated assets (CSS, JavaScript, images) without requiring you to modify your existing content or workflow.
ngx_pagespeed speeds up your site and reduces page load time by changing the resources on web pages to implement web performance best practices. Each optimization is implemented as a custom filter, which is executed when Nginx serves website assets. Some filters alter HTML content, while others change references to CSS, JavaScript, or images to point to more optimized versions.
Key Benefits
Compresses, resizes, and converts images to WebP format automatically.
Minifies and combines CSS and JavaScript files to reduce HTTP requests.
Extends cache lifetimes of resources by content-hashing URLs.
Collapses whitespace, removes comments, and optimizes HTML output.
For more details, see the official PageSpeed Module documentation and the ngx_pagespeed GitHub repository.
Installation
ngx_pagespeed is disabled by default in Centmin Mod. To enable it, add the following variables to your persistent config file at /etc/centminmod/custom_config.inc and then recompile Nginx via menu option 4.
NGINX_PAGESPEED='y'
NGXDYNAMIC_NGXPAGESPEED='y'
Configuration Variables
| Variable | Description |
|---|---|
| NGINX_PAGESPEED='y' | Enable ngx_pagespeed module compilation. Set to 'n' to disable. |
| NGXDYNAMIC_NGXPAGESPEED='y' | Compile as dynamic module (recommended) instead of static module. |
| NGXPGSPEED_VER | Override the default ngx_pagespeed version (e.g. '1.12.34.2-stable'). |
| NGINX_PAGESPEEDPSOL_VER | PageSpeed Optimization Library version. Should match NGXPGSPEED_VER minus the -stable suffix. |
| NGINX_PAGESPEEDGITMASTER='n' | Use git master branch instead of a tagged release. Recommended to keep disabled. |
Enabling in Vhost Configs
After recompiling Nginx with PageSpeed support, you need to include the PageSpeed config files in each vhost's server {} block. For new vhosts created by Centmin Mod, these lines are already present but commented out. Uncomment them to enable:
# ngx_pagespeed & ngx_pagespeed handler
include /usr/local/nginx/conf/pagespeed.conf;
include /usr/local/nginx/conf/pagespeedhandler.conf;
include /usr/local/nginx/conf/pagespeedstatslog.conf;
Then enable PageSpeed server-wide using the pscontrol command:
pscontrol on
Verifying Installation
Check if ngx_pagespeed is running by looking for the X-Page-Speed response header:
curl -I http://localhost/?ModPagespeed=on
A successful response will include:
HTTP/1.1 200 OK
Server: nginx
X-Page-Speed: 1.12.34.2-stable
Cache-Control: max-age=0, no-cache
Configuration
Configuration Files
When you install or upgrade Nginx with PageSpeed support via menu option 4, three configuration files and the pscontrol utility are created:
| File | Purpose |
|---|---|
| /usr/local/nginx/conf/pagespeed.conf | Main ngx_pagespeed settings and filter configuration |
| /usr/local/nginx/conf/pagespeedhandler.conf | Location directives for pagespeed optimized resources |
| /usr/local/nginx/conf/pagespeedstatslog.conf | Statistics and console logging settings |
| /usr/bin/pscontrol | Command-line shortcut to manage PageSpeed on/off and edit configs |
pscontrol Commands
The pscontrol utility provides quick shortcuts for managing PageSpeed:
| Command | Action |
|---|---|
| pscontrol on | Enable PageSpeed server-wide and restart Nginx |
| pscontrol off | Disable PageSpeed server-wide and restart Nginx |
| pscontrol edit | Edit pagespeed.conf in nano text editor |
| pscontrol handler | Edit pagespeedhandler.conf |
| pscontrol editstats | Edit pagespeedstatslog.conf |
| pscontrol admin | Edit pagespeedadmin.conf |
| pscontrol statson | Enable statistics and logging |
| pscontrol statsoff | Disable statistics and logging |
Core Configuration
The main pagespeed.conf controls filters, cache, and optimization settings. By default, PageSpeed uses CoreFilters rewrite level with additional collapse_whitespace and remove_comments filters enabled:
# Default state (off until enabled via pscontrol)
pagespeed off;
# File cache settings
pagespeed FileCachePath /var/ngx_pagespeed_cache;
# Rewrite level and filters
pagespeed RewriteLevel CoreFilters;
pagespeed EnableFilters collapse_whitespace,remove_comments;
# Image optimization tuning
pagespeed AvoidRenamingIntrospectiveJavascript on;
pagespeed ImageInlineMaxBytes 3072;
pagespeed CssImageInlineMaxBytes 0;
pagespeed MaxInlinedPreviewImagesIndex -1;
pagespeed MinImageSizeLowResolutionBytes 3072;
Image Optimization
ngx_pagespeed can automatically compress, resize, and convert images. By default, rewrite_images is disabled in Centmin Mod's default configuration because the module is typically installed on low-end VPS with limited CPU and memory. If your server has sufficient resources, you can enable image optimization filters.
Note
It is recommended to optimize images before uploading them to your server. Use PageSpeed's image optimization filters as an additional layer, not as your only optimization strategy.
Image-Related Filters
Enable these filters in pagespeed.conf as needed:
# Enable image rewriting (compression & resizing)
pagespeed EnableFilters rewrite_images;
# Convert PNG to JPEG where applicable
pagespeed EnableFilters convert_png_to_jpeg;
# Convert JPEG to WebP for supported browsers
pagespeed EnableFilters convert_jpeg_to_webp;
# Lossless WebP conversion
pagespeed EnableFilters convert_to_webp_lossless;
# Lazy load images (defer offscreen images)
pagespeed EnableFilters lazyload_images;
To explicitly disable image rewriting (the default), keep this line in your pagespeed.conf:
pagespeed DisableFilters rewrite_images;
CSS & JavaScript Optimization
ngx_pagespeed provides several filters for optimizing CSS and JavaScript delivery. These filters can minify code, combine files to reduce HTTP requests, and reorder resources for better loading performance.
Available CSS/JS Filters
| Filter | Description |
|---|---|
| rewrite_css | Minifies CSS files by removing whitespace and comments |
| rewrite_javascript | Minifies JavaScript files to reduce file size |
| combine_css | Combines multiple CSS files into one to reduce HTTP requests |
| combine_javascript | Combines multiple JS files into one to reduce HTTP requests |
| move_css_above_scripts | Moves CSS <link> elements above <script> tags for better rendering |
| make_google_analytics_async | Converts synchronous Google Analytics to async |
To enable any of these filters, uncomment the corresponding line in pagespeed.conf (accessible via pscontrol edit):
# Enable CSS and JS minification
pagespeed EnableFilters rewrite_css;
pagespeed EnableFilters rewrite_javascript;
# Enable combining (reduces HTTP requests)
pagespeed EnableFilters combine_css;
pagespeed EnableFilters combine_javascript;
# Prevent combining across different paths
# pagespeed CombineAcrossPaths off;
Cache Configuration
ngx_pagespeed stores optimized resources in a file cache by default. You can optionally use Memcached for faster cache storage.
File Cache
The default file cache directory is /var/ngx_pagespeed_cache. You can tune cache size and cleanup intervals:
# File cache path (must be writable by nginx)
pagespeed FileCachePath /var/ngx_pagespeed_cache;
# Optional: tune cache limits
pagespeed FileCacheSizeKb 102400;
pagespeed FileCacheCleanIntervalMs 3600000;
pagespeed FileCacheInodeLimit 500000;
Memcached Integration
For better performance, you can store PageSpeed resources in Memcached. The default Centmin Mod Memcached installation runs on port 11211:
# Memcached cache backend (requires Memcached server)
pagespeed MemcachedThreads 1;
pagespeed MemcachedServers "localhost:11211";
pagespeed MemcachedTimeoutUs 100000;
Statistics & Admin Console
Enable PageSpeed statistics logging for monitoring and the admin console:
# Pagespeed stats logging
pagespeed Statistics on;
pagespeed StatisticsLogging on;
pagespeed LogDir /var/log/pagespeed;
Access the admin console at yourdomain.com/pagespeed_global_admin/. By default, access is restricted to 127.0.0.1. To allow remote access, add your IP to pagespeedhandler.conf via pscontrol handler.
Filter Reference
ngx_pagespeed organizes filters into rewrite levels. The default CoreFilters level includes a set of safe-to-use filters. You can add individual filters on top of CoreFilters.
CoreFilters (Default)
CoreFilters includes these optimizations automatically:
- Add
HEADsection - Combine multiple CSS and JS files
- Flatten CSS imports
- Inline small CSS and JS resources
- Inline critical CSS above the fold
- Minify JavaScript
- Rewrite CSS to load asynchronously
- Rewrite and compress images
- Extend cache lifetimes
Additional Filters
These filters can be individually enabled in pagespeed.conf:
| Filter Name | Effect |
|---|---|
| collapse_whitespace | Removes excess whitespace from HTML output |
| remove_comments | Strips HTML comments to reduce page size |
| extend_cache | Extends cache lifetimes by content-hashing resource URLs |
| rewrite_images | Compresses and optimizes images on the fly |
| lazyload_images | Defers loading of offscreen images until they are visible |
| insert_dns_prefetch | Adds DNS prefetch tags for external domains found in the page |
| convert_jpeg_to_webp | Serves WebP images to browsers that support it |
| convert_png_to_jpeg | Converts PNG images without transparency to JPEG |
A/B Testing with PageSpeed
ngx_pagespeed supports A/B experiment configuration via RunExperiment, allowing you to test optimized vs. unoptimized pages and measure impact through Google Analytics.
Troubleshooting
Disabling for Specific URLs
You can dynamically toggle PageSpeed on a per-URL basis by appending query parameters:
# Disable for a specific URL
yourdomain.com/?ModPagespeed=off
# Enable for a specific URL
yourdomain.com/?ModPagespeed=on
Disabling per Vhost
To disable PageSpeed for a specific vhost, add the following to that domain's vhost configuration file (after the include pagespeed.conf line):
# For ngx_pagespeed 1.13.35.1+
pagespeed unplugged;
# For older versions (< 1.13.35.1)
pagespeed off;
Excluding Specific Resources
To exclude specific URLs, files, or directories from PageSpeed processing, add pagespeed Disallow entries to pagespeed.conf:
pagespeed Disallow "*/jquery-ui-1.8.2.custom.min.js";
pagespeed Disallow "*/js_tinyMCE.js";
Upgrading ngx_pagespeed
To upgrade, update the version variables in /etc/centminmod/custom_config.inc and run menu option 4 to recompile Nginx:
NGINX_PAGESPEED='y'
NGXPGSPEED_VER='1.12.34.2-stable'
NGINX_PAGESPEEDPSOL_VER='1.12.34.2'
Compilation Errors
If Nginx compilation fails with a missing PSOL library, delete the existing downloaded files and re-run menu option 4:
# Replace version numbers with the version that failed
rm -rf /svr-setup/ngx_pagespeed-release-1.12.34.2-stable
rm -rf /svr-setup/release-1.12.34.2-stable.tar.gz
Centmin Mod automatically logs Nginx upgrade operations. Check logs at:
ls -lahrt /root/centminlogs/
Debug Headers
You can customize the X-PageSpeed header value or enable the message buffer for debugging:
# Custom X-PageSpeed header value
pagespeed XHeaderValue "ngx_pagespeed";
# Enable message buffer for debugging (set to 0 to disable)
pagespeed MessageBufferSize 100000;
With MessageBufferSize enabled, check the message log at yourdomain.com/ngx_pagespeed_message to see which files are being processed or excluded.
Related Documentation
Learn more about Nginx configuration and optimization with Centmin Mod.