Compile Nginx with ngx_pagespeed Module on Ubuntu Server

ngx_pagespeed is an open-source Nginx module that automatically applies best practices to optimize website speed. In this tutorial, we will discuss how to compile Nginx with ngx_pagespeed module on Ubuntu server LTS.

Step 1: Back up Nginx Configuration Files

Once Nginx is compiled and installed, your original Nginx config files will be overwritten. You can use the following command to back up the main config file and server block files to your home directory. The tilde (~) represents your home directory.

cp /etc/nginx/nginx.conf /etc/nginx/sites-available/*.conf /etc/nginx/conf.d/*.conf ~

Step 2: Add Official Nginx Repository

The tutorial will demonstrate compiling the latest Nginx mainline version. We add the official Nginx repository as shown below.

First, fetch the Nginx GPG key and import it to the Ubuntu server system.

wget http://nginx.org/keys/nginx_signing.key

sudo apt-key add nginx_signing.key

Then create a source list file for Nginx.

sudo nano /etc/apt/sources.list.d/nginx.list

Add the following two lines to this file. The deb-src line allows us to download Nginx source packages with apt source command.

deb http://nginx.org/packages/mainline/ubuntu/ focal nginx
deb-src http://nginx.org/packages/mainline/ubuntu/ focal nginx

If you use Ubuntu 22.04, then replace focal with jammy.

Press Ctrl+O to save the file. Press Ctrl+X to close the file. Then update the local package index.

sudo apt update

Now the Nginx official repository is added to the Ubuntu server.

Step 3: Download Nginx Source Package

We will make a nginx directory under the home directory to store the Nginx sources and then cd into that directory.

mkdir ~/nginx && cd ~/nginx

Install dpkg-dev and download the Nginx source package with the below command:

sudo apt install dpkg-dev
sudo apt source nginx

Check out the downloaded files.

ls ~/nginx/

Output:

nginx-1.23.2                              nginx_1.23.2-1~focal.dsc
nginx_1.23.2-1~focal.debian.tar.xz        nginx_1.23.2.orig.tar.gz

Step 4: Download ngx_pagespeed Source Package

To compile Nginx with ngx_pagespeed module, we also need ngx_pagespeed source package. Go to Github ngx_pagespeed download page. Download the latest beta release to your home directory (v1.13.35.2-beta at the time of this writing). You may need to change the version number.

cd ~

wget https://codeload.github.com/pagespeed/ngx_pagespeed/zip/v1.13.35.2-beta

unzip it:

sudo apt-get install unzip

unzip v1.13.35.2-beta

cd to the newly-created directory:

cd incubator-pagespeed-ngx-1.13.35.2-beta/

We also need to download the PSOL library. (PageSpeed Optimization Library) and extract it. The version number corresponds to the PageSpeed version number.

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

tar xvf 1.13.35.2-x64.tar.gz

It will create a psol directory under ~/incubator-pagespeed-ngx-1.13.35.2-beta directory and that’s where it needs to be.

Step 5: Add ngx_pagespeed Module to Nginx Compilation Rules

Edit the Nginx compilation rule file.

sudo nano ~/nginx/nginx-1.23.2/debian/rules

At the end of COMMON_CONFIGURE_ARGS section, add the following line. Replace username with your actual username. This line specifies the location of ngx_pagespeed module.

--add-module=/home/username/ngx_pagespeed-1.13.35.2-beta

This tutorial downloads the ngx_pagespeed source page to the home directory. If you use root account, then replace /home/username with /root. because the home directory for the root user is /root.

Also notice that you need to append a backslash at the --with-ld-opt line like the screenshot below. If you don’t, the --add-module line you added will be ignored when Nginx is being compiled.

Now save and close the file.

Step 6: Start the Compilation

Make sure you are in the Nginx source directory.

cd ~/nginx/nginx-1.23.2/

Install all the needed dependencies to build our Nginx deb package.

sudo apt build-dep nginx

Now use the following command to build the deb package.

sudo dpkg-buildpackage -b

Take a cup of coffee and wait a few minutes. On a single-core KVM VPS, this build process took around 10 minutes. When it’s done, there will be 7 .deb files in ~/nginx/ directory. We only need to install the nginx_1.11.1-1~xenial_amd64.deb or nginx_1.11.1-1~xenial_i386.deb package, depending on your OS architecture. The others are Nginx dynamic module package and a debug package. You can install them as well if you like.

If you have installed Nginx before, it’s time to remove the old version and then install the new version.

sudo apt remove nginx nginx-common nginx-full

cd ~/nginx

sudo dpkg -i nginx_1.23.2-1~focal_amd64.deb

or

sudo dpkg -i nginx_1.23.2-1~focal_i386.deb

Now let’s start Nginx.

sudo systemctl start nginx

If you see the following error message.

Failed to start nginx.service: Unit nginx.service is masked.

Then unmask Nginx and issue the start command again.

sudo systemctl unmask nginx

Note that the Nginx process might run as user nginx or www-data. This can be changed by editing the first line in /etc/nginx/nginx.conf file. Just make sure Nginx run as the same user with PHP-FPM.

Now check the config arguments of Nginx.

sudo nginx -V

If you see the following line at the end then ngx_pagespeed module is successfully added to Nginx.

--add-module=/home/username/ngx_pagespeed-1.13.35.2-beta

Step 7: Enable ngx_pagespeed Module

PageSpeed is installed along with Nginx, but it’s disabled by default. Before enabling it, I recommend you test your website speed at pingdom.com or webpagetest.org. Pay attention to the page size, number of requests, page load time, etc. After PageSpeed is enabled, do a test again so as to compare the two results.

Create a folder for Pagespeed caches and change its ownership to Nginx user (www-data or nginx) 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

Save and close your server block config file. Then reload Nginx.

sudo systemctl reload nginx

8. Check if 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 pictures on your website has been converted to webp format. webp can greatly reduce image file size.

You can also find ngx_pagespeed is working by comparing your website speed test.

Also on your server you can issue the following command:

curl -I -p http://your-domain.com| grep X-Page-Speed

You will see X-Page-Speed and its version number.

X-Page-Speed: 1.13.35.2-7423

9. Hold Nginx from Being Upgraded

If a newer version of Nginx is available in the repository, the apt-get upgrade command will upgrade Nginx by default and you ngx_pagespeed module will be gone. So we need to prevent Nginx from being upgraded. This can be achieved by the following command:

sudo apt-mark hold nginx

To show what packages are held:

apt-mark showhold

Some pagespeed directives you might want to add in Nginx server block config files that are not in CoreFilters.

pagespeed EnableFilters collapse_whitespace;
pagespeed EnableFilters lazyload_images;
pagespeed EnableFilters insert_dns_prefetch;

Don’t forget to reload Nginx after you modify server block config files.

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

Comments, questions or suggestions are always welcome. If you found this post useful, 🙂 please share it with your friends on social media! Stay tuned for more Linux tutorials.