How to Install PageSpeed Module with Nginx on Ubuntu 20.04, Ubuntu 18.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 the Latest Version of Nginx on Ubuntu
PageSpeed integrates with Nginx as a dynamic module, which allows you to compile source code of individual modules without compiling Nginx itself.
The Nginx binary needs to be compiled with the --with-compat
argument, which will make dynamic modules binary-compatible with your existing Nginx binary. However, not every Nginx binary shipped from the default Debian/Ubuntu repository is compiled with the --with-compat
argument. To make things easier, we can install the latest version of Nginx from the ondrej/nginx-mainline
PPA, which is maintained by a Debian developer.
Note: The nginx.org repository also provides the latest version of Nginx. However, the ondrej/nginx-mainline
PPA provides extra dynamic modules that you might find useful.
Run the following commands to install the latest version of Nginx.
sudo add-apt-repository ppa:ondrej/nginx-mainline -y sudo apt update sudo apt install nginx-core nginx-common nginx nginx-full
During the installation process, it may tell you that the package distributor has shipped an updated version of the main configuration file. It’s recommended to press n
to keep your current version. You can always examine the difference later.
By default, only the binary repository is enabled. We also need to enable the source code repository in order to download Nginx source code. Edit the Nginx mainline repository file.
sudo nano /etc/apt/sources.list.d/ondrej-ubuntu-nginx-mainline-*.list
Find the line that begins with # deb-src
.
# deb-src http://ppa.launchpad.net/ondrej/nginx-mainline/ubuntu/ focal main
Remove the #
character to enable this source code repository.
deb-src http://ppa.launchpad.net/ondrej/nginx-mainline/ubuntu/ focal main
Save and close the file. Then update repository index.
sudo apt update
Now check the configure arguments of Nginx with the following command:
sudo nginx -V
All Nginx binaries in the PPA are 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 -p /usr/local/src/nginx
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
If you see the following warning message, you can safely ignore it.
W: Download is performed unsandboxed as root as file 'nginx_1.19.5-0ubuntu1.dsc' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)
Check out the downloaded files.
ls
Sample output:
nginx-1.19.5 nginx_1.19.5-1~bionic.debian.tar.xz nginx_1.19.5-1~bionic.dsc nginx_1.19.5.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.19.5
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 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
Next Step
I hope this tutorial helped you install PageSpeed module with Nginx on Ubuntu 18.04 and Ubuntu 20.04. You may also want to set up the ModSecurity web application firewall to protect your website from hacking.
And as always, if you found this post useful, then subscribe to our free newsletter for more tips and tricks 🙂
This post is very useful. Thank you so much 🙂
Don’t work thanks
thank you for your great post . i’m using webinoly , their structure are little different . how we can install on this kind of lemp installation
Thanks, this is the only way to install pagespeed in u18 that works for me.
There are a handful of tutorials explaining how to install pagespeed with nginx. This is the BEST one.
There is no need to compile nginx itself!
Thanks
Hmm does not work for me. I’m using Ubuntu 20.04.1 LTS.
Apt installs nginx 1.18 while the source gets 1.17
In the end when the module is built I get:
nginx: [emerg] module “/usr/share/nginx/modules/ngx_pagespeed.so” version 1017010 instead of 1018000 in /etc/nginx/nginx.conf:1
Looks like the module is being built against the source (1.17) and not towards the binary version (1.18)?
When a new version of Nginx is available, you should download the new Nginx source package and compile the PageSpeed module again.
Hey Xiao, thanks for the reply!
When I did
with the normal Ubuntu repo (focal main restricted), I sort of was expecting that if I enabled the dev-src, the nginx versions would at least match (seems to not be the case)
Can I select a specific branch of nginx somehow so that the source and binaries would match?