// Tutorial //

How To Add ngx_pagespeed to Nginx on Ubuntu 14.04

Published on September 22, 2015
Default avatar
By Toli
Developer and author at DigitalOcean.
How To Add ngx_pagespeed to Nginx on Ubuntu 14.04
Not using Ubuntu 14.04?Choose a different version or distribution.
Ubuntu 14.04

Introduction

ngx_pagespeed, or just pagespeed, is an Nginx module designed to optimize your site automatically by reducing the size of its resources and hence the time the clients’ browsers need to load it. If you are not acquainted with it already, please check its official site.

This article will guide you through the installation and configuration of the pagespeed module for Nginx. It’s important to know that Nginx does not support Dynamic Loading of Modules available in other web servers such as Apache. Since Nginx doesn’t support this feature, you need to build Nginx from source to add the module.

Having your own custom package comes with one disadvantage — you are solely responsible for updating it when there is a new version. Take this into account when weighing the pros and cons of using ngx_pagespeed.

Prerequisites

This guide has been written for Ubuntu 14.04. A CentOS 7 version and a Debian 8 version are available as well.

Before following this tutorial, please make sure you complete the following prerequisites:

Except otherwise noted, all of the commands that require root privileges in this tutorial should be run as a non-root user with sudo privileges.

Step 1 — Download the Source and Its Dependencies

Before anything else, we have to make sure the list of packages available via apt-get has been updated:

  1. sudo apt-get update

Next, we have to satisfy all the dependencies needed to run Nginx. For this purpose run the command:

  1. sudo apt-get build-dep nginx

After that, create a folder in your home directory to download the source package for Nginx:

  1. mkdir ~/custom-nginx

Change to this newly created directory:

  1. cd ~/custom-nginx

Then, download the Nginx source package in this directory with the command:

  1. sudo apt-get source nginx

To confirm we are on the same page, list the content of the folder ~/custom-nginx:

  1. ls ~/custom-nginx

The result should look like this:

Output of ls ~/custom-nginx
nginx-1.4.6 nginx_1.4.6-1ubuntu3.3.debian.tar.gz nginx_1.4.6-1ubuntu3.3.dsc nginx_1.4.6.orig.tar.gz

As you can see, the version of the Nginx source package is 1.4.6 at the time of writing this tutorial. To start adding the ngx_pagespeed module, you first need to go to the modules folder within the extracted folder nginx-1.4.6:

  1. cd nginx-1.4.6/debian/modules

In this directory, download the latest ngx_pagespeed source archive from its Github repository with the command:

  1. sudo wget https://github.com/pagespeed/ngx_pagespeed/archive/master.zip

Once the download completes, you will need the unzip utility to extract it. If you don’t already have unzip, install it with the command:

  1. sudo apt-get install unzip

After that extract the downloaded file with the command:

  1. sudo unzip master.zip

This will create a new directory called ngx_pagespeed-master inside your ~/nginx-1.4.6/debian/modules directory. For convenience rename this directory to just ngx_pagespeed with the command:

  1. sudo mv ngx_pagespeed-master ngx_pagespeed

Go inside the new ngx_pagespeed directory:

  1. cd ngx_pagespeed

From there, download the PageSpeed Optimization Libraries (psol) which are required for the compilation:

  1. sudo wget https://dl.google.com/dl/page-speed/psol/1.9.32.6.tar.gz

If the link to the psol archive is not working at the time you are reading this article, just skip this step. If you are missing the libraries during the compilation in the next steps, you will see an error with updated instructions for how to get the package later.

Finally, extract the psol package inside the ~/custom-nginx/nginx-1.4.6/debian/modules/ngx_pagespeed directory:

  1. sudo tar -xzvf 1.9.32.6.tar.gz

Step 2 — Customize the Source

At this point you are ready to customize the compilation rules and include ngx_pagespeed in the installation. For this purpose edit the file ~/custom-nginx/nginx-1.4.6/debian/rules with your favorite editor:

  1. sudo nano ~/custom-nginx/nginx-1.4.6/debian/rules

There you have five different scenarios for building Nginx’s packages: core, full, light, extras and naxsi. As their names suggest, common contains the common Nginx files without a server, full includes a server with the most popular modules, light creates a server with only the essential modules, extras is for a server with some extra fancy modules in it, and naxsi has in addition the naxsi module (a web application firewall).

Let’s assume that you need a light Nginx setup plus ngx_pagespeed. Thus, at the end of the light_configure_flags configuration block add the line:

~/custom-nginx/nginx-1.4.6/debian/rules
--add-module=$(MODULESDIR)/ngx_pagespeed \

Please don’t forget to add a backslash (\) at the end of the row. The whole configuration block should look like this:

~/custom-nginx/nginx-1.4.6/debian/rules
config.status.light: config.env.light
        cd $(BUILDDIR_light) && ./configure  \
            $(common_configure_flags) \
            --with-http_gzip_static_module \
            --without-http_browser_module \
            --without-http_geo_module \
            --without-http_limit_req_module \
            --without-http_limit_zone_module \
            --without-http_memcached_module \
            --without-http_referer_module \
            --without-http_scgi_module \
            --without-http_split_clients_module \
            --without-http_ssi_module \
            --without-http_userid_module \
            --without-http_uwsgi_module \
            --add-module=$(MODULESDIR)/nginx-echo \
            --add-module=$(MODULESDIR)/ngx_pagespeed \
            >$@
        touch $@

You could add the same line to the other build scenarios too if you find a different Nginx setup more convenient.

Next, increase the source package version, since this will help you pin the package later. To achieve this, open the changelog file with a text editor:

  1. sudo nano ~/custom-nginx/nginx-1.4.6/debian/changelog

The first line of the changelog file represents the current package version (1.4.6-1ubuntu3.3) and the Ubuntu codename (trusty). Add a custom tag such as pagespeed at the end of the version number preceded by a hyphen like this:

changelog
nginx (1.4.6-1ubuntu3.3-pagespeed) trusty-proposed; urgency=medium

Step 3 — Build and Install Nginx with Pagespeed Module

Now that you have customized the build to include the ngx_pagespeed module, you are ready to build Nginx.

Go to the directory ~/custom-nginx/nginx-1.4.6/ with the command:

  1. cd ~/custom-nginx/nginx-1.4.6/

From here, run the command to build the new custom Nginx binary packages:

  1. sudo dpkg-buildpackage -b

The build process takes around 10 minutes at most. If you are worried that you might be disconnected during this time you could try using screen as described in this article.

If you have followed all the instructions, the build process should complete without any errors. To find the new custom Nginx packages go one directory up to ~/custom-nginx/ with the command:

  1. cd ~/custom-nginx/

List the contents of the ~/custom-nginx/ directory:

  1. ls ~/custom-nginx/

You should find a lot of .deb packages. The ones you need are called nginx-common_1.4.6-1ubuntu3.3-pagespeed_all.deb (containing the common Nginx files) and nginx-light_1.4.6-1ubuntu3.3-pagespeed_amd64.deb (containing your custom light server). The pagespeed part may vary if you have specified a different custom tag in the changelog file.

To install your custom Nginx with pagespeed module run the command:

  1. sudo dpkg -i nginx-common_1.4.6-1ubuntu3.3-pagespeed_all.deb nginx-light_1.4.6-1ubuntu3.3-pagespeed_amd64.deb

Step 4 — Enable the Pagespeed Module

You now have Nginx installed. The next step is to enable the ngx_pagespeed module.

Before enabling the module, you have to create a folder, where it will cache the files for your website:

  1. sudo mkdir -p /var/ngx_pagespeed_cache

Make sure to change the ownership of this folder to the Nginx user so that the web server can store files in it:

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

Then, open the main Nginx configuration file nginx.conf in your favorite text editor like this:

  1. sudo nano /etc/nginx/nginx.conf

In this file add the following lines to the http block and save the changes:

/etc/nginx/nginx.conf
##
# Pagespeed Settings
##

pagespeed on;
pagespeed FileCachePath /var/ngx_pagespeed_cache;

You can add these lines anywhere in the http block, but in our example, we are adding it to the end of the block.

This is how the /etc/nginx/nginx.conf file should look now:

/etc/nginx/nginx.conf
...
http {

        ##
        # Basic Settings
        ##

        sendfile on;
        tcp_nopush on;
        tcp_nodelay on;
        keepalive_timeout 65;
        types_hash_max_size 2048;
        # server_tokens off;

        # server_names_hash_bucket_size 64;
        # server_name_in_redirect off;

        ##
        # Pagespeed Settings
        ##
        
        pagespeed on;
        pagespeed FileCachePath /var/ngx_pagespeed_cache;
...

Also, you need to add pagespeed configuration lines to every server block file located in /etc/nginx/sites-available. For example, edit the /etc/nginx/sites-available/default file:

  1. sudo nano /etc/nginx/sites-available/default

Add the following to the end of the server block:

/etc/nginx/sites-available
#  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 ~ "^/ngx_pagespeed_static/" { }
location ~ "^/ngx_pagespeed_beacon" { }

The above pagespeed configuration lines ensure that pagespeed will optimize every site’s resources.

Finally, restart Nginx server for the changes to take effect:

  1. sudo service nginx restart

Step 5 — Test the Installation

To check if ngx_pagespeed module has been installed successfully, run the Nginx binary like this:

  1. sudo /usr/sbin/nginx -V

If the installation was successful, you should see the ngx_pagespeed module listed among the other modules:

Output
nginx version: nginx/1.4.6 ... --add-module=/home/your_user/custom-nginx/nginx-1.4.6/debian/modules/ngx_pagespeed

The above doesn’t mean yet that the pagespeed is enabled and works for your site. To confirm this you can use curl, a tool and a library for client-side URL transfers. If you don’t have curl already installed, then install it with the command:

  1. sudo apt-get install curl

After that check for the X-Page-Speed header like this:

  1. curl -I -p http://localhost| grep X-Page-Speed

If the ngx_pagespeed module works fine, you should see it in the output along with its version:

Output
X-Page-Speed: 1.9.32.6-7321

If you don’t see this header, make sure that you have enabled pagespeed as per the instructions from the previous step.

Step 6 — Pin Your Custom Nginx Package

To prevent your custom Nginx package from being replaced in the future by apt with a more recent release of Nginx, you should pin (hold) your package from being upgraded by the following steps:

Create a new nginx file in /etc/apt/preferences.d:

  1. sudo nano /etc/apt/preferences.d/nginx

Then paste the following lines in it and save it:

/etc/apt/preferences.d/nginx
Package: nginx-light
Pin: version 1.4.6-1ubuntu3.3-pagespeed
Pin-Priority: 1001

Please make sure to specify the Nginx package you have decided to use. In our example, it was nginx-light. Also, specify the exact version along with your custom tag like 1.4.6-1ubuntu3.3-pagespeed.

Conclusion

That’s how you can build Nginx with a custom module, pagespeed. These steps are valid for any other module that is not already available in Nginx. Furthermore, the whole process for installing a package from source is similar for other software packages you might need to customize. Just don’t forget that you will have to maintain and re-install these packages by yourself when there is a new version.


Want to learn more? Join the DigitalOcean Community!

Join our DigitalOcean community of over a million developers for free! Get help and share knowledge in our Questions & Answers section, find tutorials and tools that will help you grow as a developer and scale your project or business, and subscribe to topics of interest.

Sign up
About the authors
Default avatar
Toli

author

Developer and author at DigitalOcean.

Default avatar
Tammy Fox

editor

Developer and author at DigitalOcean.

Still looking for an answer?

Was this helpful?
10 Comments

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

Hi guys

i’m loving this stuff so far but im getting an error

/root/custom-nginx/nginx-1.9.3/debian/modules/ngx_pagespeed/src/ngx_base_fetch.cc
In file included from /root/custom-nginx/nginx-1.9.3/debian/modules/ngx_pagespeed/src/ngx_server_context.h:24:0,
                 from /root/custom-nginx/nginx-1.9.3/debian/modules/ngx_pagespeed/src/ngx_base_fetch.h:59,
                 from /root/custom-nginx/nginx-1.9.3/debian/modules/ngx_pagespeed/src/ngx_base_fetch.cc:20:
/root/custom-nginx/nginx-1.9.3/debian/modules/ngx_pagespeed/src/ngx_message_handler.h:35:53: fatal error: pagespeed/system/system_message_handler.h: No such file or directory
compilation terminated.
objs/Makefile:1234: recipe for target 'objs/addon/src/ngx_base_fetch.o' failed
make[3]: *** [objs/addon/src/ngx_base_fetch.o] Error 1
make[3]: Leaving directory '/root/custom-nginx/nginx-1.9.3/debian/build-light'
Makefile:8: recipe for target 'build' failed
make[2]: *** [build] Error 2
make[2]: Leaving directory '/root/custom-nginx/nginx-1.9.3/debian/build-light'
debian/rules:159: recipe for target 'build.arch.light' failed
make[1]: *** [build.arch.light] Error 2
make[1]: Leaving directory '/root/custom-nginx/nginx-1.9.3'
debian/rules:141: recipe for target 'build' failed
make: *** [build] Error 2
dpkg-buildpackage: error: debian/rules build gave error exit status 2

psol 1.9.32.6.tar.gz nginx-1.9.3 ubuntu 15

any ideas?

Is it advisable to use this guide on a fresh digitalocean LEMP 16.04 droplet to install ngx_pagespeed?

Whoever found error: debian/rules build gave error exit status 2 Please try install latest pagespeed. You should find details here - https://modpagespeed.com/doc/build_ngx_pagespeed_from_source

After downloading pagespeed & psol, follow remaining of this tutorial.

Ive updated a full comprehensive tutorial on NGINX Pagespeed Module, working on markbarry.info

don’t woork should update

from /root/custom-nginx/nginx-1.4.6/debian/modules/ngx_pagespeed/src/ngx_base_fetch.cc:19: /root/custom-nginx/nginx-1.4.6/debian/modules/ngx_pagespeed/psol/include/pagespeed/kernel/base/proto_util.h:24:59: fatal error: google/protobuf/io/zero_copy_stream_impl_lite.h: No such file or directory #include “google/protobuf/io/zero_copy_stream_impl_lite.h” ^ compilation terminated. make[2]: *** [objs/addon/src/ngx_base_fetch.o] Error 1 make[2]: Leaving directory /root/custom-nginx/nginx-1.4.6/debian/build-light' make[1]: *** [build] Error 2 make[1]: Leaving directory /root/custom-nginx/nginx-1.4.6/debian/build-light’ make: *** [build-arch.light] Error 2

any one help me

This is out of date; there’s now an automated installer for ngx_pagespeed: build_ngx_pagespeed_from_source

Additionally, it tells people to use https://github.com/pagespeed/ngx_pagespeed/archive/master.zip with PSOL 1.9, which hasn’t worked since we released 1.10

Hi, is this tutorial still valid for Ubuntu 16.04?

Hello!

Thanks by this tutorial.

Please, i´m getting this result at curl -I:

X-Page-Speed: 1.11.33.2-0 Cache-Control: max-age=0, no-cache, no-store, must-revalidate, post-check=0, pre -check=0

I´m trying to use w3 total cache together, using:

“include /var/www/nginx.conf” (w3 total cache file) at “/etc/nginx/nginx.conf” on location /

It´s not working…

I can´t configure cache… do you have suggestions?

Thanks and Regards,

Tony

For all those who stumble upon the compiler errors during the PageSpeed inclusion, please bare in mind you might be running out of memory on your server! ( I have stumbled upon this problem during custom compilation of NGINX 1.10.0 from the source).

To battle that, please install and enable a swap memory file!

cd /
sudo dd if=/dev/zero of=swapfile bs=1M count=3000

This will create a 3GB swap file in the root of your server. Now you need to enable the swap file.

sudo mkswap swapfile
sudo swapon swapfile

In order to check if the file has been initialized and used simply do a check on meminfo.

 cat /proc/meminfo

After the swap has been created and activated, repeat the package building step.