Installing and Configuring Google's ngx_pagespeed Module for Nginx

Installing the ngx_pagespeed Module

ngx_pagespeed is a Nginx module provided by Google to automatically optimize website performance (e.g., compressing images, merging CSS/JS). Below are the steps to compile and install this module into Nginx.

1. Install Dependencies

Install the necessary compilation tools and libraries based on your Linux distribution.

RedHat, CentOS, or Fedora

sudo yum install gcc-c++ pcre-devel zlib-devel make unzip

Ubuntu or Debian

sudo apt-get install build-essential zlib1g-dev libpcre3 libpcre3-dev unzip

2. Download ngx_pagespeed

cd
NPS_VERSION=1.13.35.2
wget https://github.com/apache/incubator-pagespeed-ngx/archive/v${NPS_VERSION}.zip
unzip v${NPS_VERSION}.zip
cd incubator-pagespeed-ngx-${NPS_VERSION}/
wget https://dl.google.com/dl/page-speed/psol/${NPS_VERSION}-x64.tar.gz
tar -xzvf ${NPS_VERSION}-x64.tar.gz

Note: Visit the GitHub releases page to get the latest stable version number. The version (1.13.35.2) and PSOL package name (-x64) in the commands above may need adjustment.

3. Download and Compile Nginx

cd
# Get the latest version from http://nginx.org/en/download.html
NGINX_VERSION=1.18.0
wget http://nginx.org/download/nginx-${NGINX_VERSION}.tar.gz
tar -xvzf nginx-${NGINX_VERSION}.tar.gz
cd nginx-${NGINX_VERSION}/
./configure --add-module=$HOME/incubator-pagespeed-ngx-${NPS_VERSION}
make
sudo make install

Special Case: If running 32-bit user space on a 64-bit kernel (e.g., some VPS environments), you may need to force 32-bit architecture: setarch i686 ./configure --add-module=$HOME/incubator-pagespeed-ngx-${NPS_VERSION}

4. Post-Installation Setup

If this is your first Nginx installation from source, you'll need to manually set up a systemd service or init script. Refer to the Nginx official documentation.

Configuring ngx_pagespeed

After installation, enable and configure ngx_pagespeed in your Nginx configuration.

Basic Enablement

Add the following directives within the http or server block of your Nginx config file (typically /usr/local/nginx/conf/nginx.conf or /etc/nginx/nginx.conf):

pagespeed on;

# Cache directory; ensure Nginx process has write permissions
pagespeed FileCachePath /var/ngx_pagespeed_cache;

# Ensure optimized resource requests are handled correctly
location ~ ".pagespeed.([a-z].)?[a-z]{2}.[^.]{10}.[^.]+" {
  add_header "" "";
}
location ~ "^/pagespeed_static/" { }
location ~ "^/ngx_pagespeed_beacon$" { }

Core Configuration Directives

• Enable/Disable: pagespeed on; or pagespeed off; (completely disables).
• Respect Vary Header: By default, PageSpeed ignores Vary: User-Agent headers for caching efficiency. To preserve this behavior, explicitly enable: pagespeed RespectVary on;
• Handle no-transform: By default, respects Cache-Control: no-transform headers (does not optimize). To force optimization, set: pagespeed DisableRewriteOnNoTransform off;
• Lowercase HTML Tags: To reduce compressed size, enable pagespeed LowercaseHtmlNames on;. Note: risky for XML files incorrectly labeled as text/html.
• Preserve Original Cache Headers: By default, PageSpeed adds Cache-Control: no-cache, max-age=0 to HTML. To keep original headers, set pagespeed ModifyCachingHeaders off; (not recommended, may cause proxy caching issues).

Virtual Host (Server Block) Configuration

PageSpeed can be configured independently in different server blocks. Global settings are inherited but can be overridden per host.

http {
  pagespeed On;
  pagespeed FileCachePath "/var/cache/ngx_pagespeed/";
  pagespeed EnableFilters combine_css,combine_javascript;

  server {
    server_name www.example1.com;
    pagespeed MapRewriteDomain cdn.example1.com *example.com;
  }

  server {
    server_name www.example2.org;
    # Disable combine_css filter for this host
    pagespeed DisableFilters combine_css;
  }

  server {
    server_name www.example3.org;
    # Completely disable PageSpeed for this host
    pagespeed off;
  }
}

Other Useful Settings

• Static Asset Path: Custom path for filter static files: pagespeed StaticAssetPrefix /custom/static/;
• List URLs on Error: For debugging, enable pagespeed ListOutstandingUrlsOnError on; to see failed fetch URLs in error logs.
• Preserve URL Relativity: Enable pagespeed PreserveUrlRelativity on; to avoid converting relative URLs to absolute, saving bytes and avoiding HTTPS proxy issues.

Using as a Reverse Proxy

ngx_pagespeed can also optimize content from a backend server. Use the proxy_pass directive in an Nginx location block and enable PageSpeed within that server or location block.

Important: After configuration changes, always test syntax with nginx -t and then reload Nginx (systemctl reload nginx or nginx -s reload).