How to Install PageSpeed Module with Nginx on Ubuntu 18.04, Ubuntu 20.04

ngx_pagespeed is an open-source Nginx module that automatically applies best practices to optimize website front-end performance. In this tutorial, I will be showing you how to install PageSpeed module with Nginx on Ubuntu 18.04 and Ubuntu 20.04 server. We are going to compile ngx_pagespeed as a dynamic module, which will simplify ongoing maintenance.

Step 1: Install or Upgrade Nginx on Ubuntu 18.04/Ubuntu 20.04

First, if you installed Nginx from a PPA, such as the ondrej/nginx PPA, you need to remove it.

sudo add-apt-repository --remove ppa:ondrej/nginx
sudo apt remove nginx nginx-common nginx-full nginx-core
sudo apt update

If you use Ubuntu 20.04, then simply run the following command to install Nginx from the default repository.

sudo apt install nginx

The Nginx binary needs to be compiled with the --with-compat argument, so later on we can just compile the PageSpeed module and no need to compile Nginx again. You can check the configure arguments of Nginx with the following command:

nginx -V

The Nginx binary from Ubuntu 20.04 repository is compiled with the --with-compat argument.

If you have already installed Nginx on Ubuntu 20.04, make sure you are using the latest version from repository.

sudo apt upgrade nginx

If you use Ubuntu 18.04, then you need to install the latest version of Nginx from nginx.org repository, because the Nginx binary from Ubuntu 18.04 repository is not compiled with the --with-compat argument.

Step 2: Download Nginx Source Package

We will make a nginx directory under /usr/local/src/ to store the Nginx source package.

sudo mkdir /usr/local/src/nginx

If you use Ubuntu 20.04, then you need to enable the deb-src repository for the main component in order to download Nginx source package. Edit the sources.list file.

sudo nano /etc/apt/sources.list

Find the following line

# deb-src http://us.archive.ubuntu.com/ubuntu/ bionic main restricted

Remove the # symbol so that this source repository will be enabled. Save and close the file. If you use Ubuntu 18.04 and follow my tutorial to install Nginx from nginx.org repository, then the deb-src repository is already enabled.

After you enable the deb-src repository, update the repository index.

sudo apt update

cd into the Nginx source directory.

cd /usr/local/src/nginx/

Download Nginx source package with the command below:

sudo apt install dpkg-dev

sudo apt source nginx

Check out the downloaded files.

ls

Output:

nginx-1.17.0
nginx_1.17.0-1~bionic.debian.tar.xz
nginx_1.17.0-1~bionic.dsc
nginx_1.17.0.orig.tar.gz

Step 3: Download ngx_pagespeed Source Package

To compile Nginx with ngx_pagespeed module, we also need ngx_pagespeed source package. Clone the ngx_pagespeed Git repository.

cd /usr/local/src

sudo apt install git

sudo git clone https://github.com/apache/incubator-pagespeed-ngx.git

cd incubator-pagespeed-ngx/

Use the latest-stable branch.

sudo git checkout latest-stable

In the PSOL_BINARY_URL file we can see the PSOL (PageSpeed Optimization Libraries) download URL.

https://dl.google.com/dl/page-speed/psol/1.13.35.2-$BIT_SIZE_NAME.tar.gz

Download PSOL and extract it.

sudo wget https://dl.google.com/dl/page-speed/psol/1.13.35.2-x64.tar.gz
sudo tar xvf 1.13.35.2-x64.tar.gz

It will create a psol directory under incubator-pagespeed-ngx directory.

Step 4: Compile  ngx_pagespeed Module

Make sure you are in the Nginx source directory.

cd /usr/local/src/nginx/nginx-1.17.0

Install build dependencies for Nginx.

sudo apt build-dep nginx
sudo apt install uuid-dev

Configure the environment with the following command. We will not compile Nginx itself, but compile the PageSpeed module only. The --with-compat flag will make the module binary-compatible with your existing Nginx binary.

sudo ./configure --with-compat --add-dynamic-module=/usr/local/src/incubator-pagespeed-ngx

Build the PageSpeed modules only, which will be finished in just a few moments.

sudo make modules

If your encounter errors, check if your server has enough RAM. The module will be save as objs/ngx_pagespeed.so, copy it to the /usr/share/nginx/modules/ directory.

sudo cp objs/ngx_pagespeed.so /usr/share/nginx/modules/

If you installed Nginx from nginx.org repostiory, you can copy it to /etc/nginx/modules/ directory instead.

sudo cp objs/ngx_pagespeed.so /etc/nginx/modules/

Step 5: Load the ngx_pagespeed Module

Edit the main Nginx configuration file.

sudo nano /etc/nginx/nginx.conf

Add the following line at the beginning of the file.

load_module modules/ngx_pagespeed.so;

Save and close the file. Then test Nginx configuration.

sudo nginx -t

If the test is successful, reload Nginx.

sudo systemctl reload nginx

Step 6: Configure PageSpeed Filters

Create a folder for pagespeed caches and change its ownership to Nginx user (www-data) so that it can be written by Nginx.

sudo mkdir -p /var/ngx_pagespeed_cache

sudo chown -R www-data:www-data /var/ngx_pagespeed_cache

Now edit Nginx server block config file.

sudo nano /etc/nginx/conf.d/your-domain.conf

Add the following pagespeed directives in server section.

# enable pagespeed module on this server block
pagespeed on;

# Needs to exist and be writable by nginx. Use tmpfs for best performance.
pagespeed FileCachePath /var/ngx_pagespeed_cache;

# Ensure requests for pagespeed optimized resources go to the pagespeed handler
# and no extraneous headers get set.
location ~ "\.pagespeed\.([a-z]\.)?[a-z]{2}\.[^.]{10}\.[^.]+" {
  add_header "" "";
}
location ~ "^/pagespeed_static/" { }
location ~ "^/ngx_pagespeed_beacon$" { }

pagespeed RewriteLevel CoreFilters;

If you host multiple websites on a single server, add the above pagespeed directives to each server block config file to enable pagespeed on each of them.

The last directive set CoreFilters as the rewrite level. PageSpeed offers 3 rewrite levels: CoreFilter, PassThrough and OptimizeForBandwidth. CoreFilter is the default as it contains filters that are considered safe for most websites.

CoreFilter contains the following filters.

   add_head
   combine_css
   combine_javascript
   convert_meta_tags
   extend_cache
   fallback_rewrite_css_urls
   flatten_css_imports
   inline_css
   inline_import_to_link
   inline_javascript
   rewrite_css
   rewrite_images
   rewrite_javascript
   rewrite_style_attributes_with_url

You may also want to add the following PageSpeed directives in Nginx server block config file that are not in CoreFilters.

pagespeed EnableFilters collapse_whitespace;
pagespeed EnableFilters lazyload_images;
pagespeed EnableFilters insert_dns_prefetch;
pagespeed EnableFilters prioritize_critical_css;
#This filter is likely to cause problems for loading your web pages. 
pagespeed EnableFilters defer_javascript;

Note that WordPress now lazy-load images by default. So if you use WordPress, you don’t need to enable the lazyload_images filter.

For a detailed explanation of each filter, go to Google PageSpeed Filter page.

Save and close your server block config file. Before Reloading Nginx, I recommend going to Google PageSpeed Insights to test your webpage. Then reload Nginx.

sudo systemctl reload nginx

Now test your PageSpeed score again, so you can see the difference.

Step 7: Check if ngx_pagespeed is Working

Go to your website. Refresh a few times then check your page source. Hit Ctrl+F key and search pagespeed. You will see that many of your website resource has been processed by pagespeed. Some css files and javascript files are combined into one file. If you use Google Chrome browser, you will see that the picture of your website is in webp file format. webp can greatly reduce image file size.

You can also find ngx_pagespeed is working by comparing your website speed test. Also on you server you can issue the following command:

curl -I -p https://youdomain.com

You will see X-Page-Speed and it’s version number.

x-page-speed: 1.13.35.2-0

Hold Nginx from Being Automatically Upgraded

If a newer version of Nginx is available in the repository, the sudo apt upgrade command will upgrade Nginx. The newer version of Nginx is not going to be compatible with the previously compiled PageSpeed module. If Nginx is upgraded by the sudo apt upgrade command, it will fail to restart.

My advice is to prevent Nginx from being upgraded when you run sudo apt upgrade command. This can be achieved by the following command:

sudo apt-mark hold nginx

When apt package manager tells you that a new version of Nginx is available, you should download the new Nginx source package and compile the PageSpeed module again. Move the the newly-compiled PageSpeed module to /usr/share/nginx/modules/ or /etc/nginx/modules/ directory. Then unhold Nginx.

sudo apt-mark unhold nginx

And upgrade Nginx.

sudo apt upgrade nginx

Once the upgrade is complete, hold Nginx again.

sudo apt-mark hold nginx

To show what packages are hold, run

apt-mark showhold

Wrap Up

I hope this tutorial helped you install PageSpeed module with Nginx on Ubuntu 18.04 and Ubuntu 20.04.