Adding PageSpeed and other Nginx modules on Ubuntu

Enable third-party Nginx modules like PageSpeed

Enabling Nginx Modules

One inconvenience with Nginx is that modules cannot be dynamically added or removed as they can in Apache. Instead, Nginx modules are specified at compile-time. If you want to add or remove any Nginx modules such as ngx_lua, ngx_http_secure_download_module, or nginx_uploadprogress_module you’ll either need to compile from source or find a PPA that meets your needs. Personally, I’ve decided to compile from source so I can include only the modules I want in order to reduce bloat.

We’ll walk through recompiling Nginx 1.6.2 to install Google’s PageSpeed Module and ngx_cache_purge for purging Nginx’s FastCGI, proxy, SCGI, and uWSGI caches. In this case Nginx is running on 64 bit Ubuntu 14.04 x64, but the process should be the same for most Ubuntu versions.

Standard APT Install

If you’re accustomed to installing software as packages using APT, your most involved Nginx install may have looked something like the below. Tools like apt-get also make installing software too easy.

sudo add-apt-repository ppa:nginx/stable
sudo apt-get update
sudo apt-get -y install nginx

This is fine for most cases, but if you want to more control over exactly what modules are loaded (beyond that provided by light, full, or extras), recompiling is your best option. Luckily, it’s very easy to do and is made even simpler by modifying the ppa:nginx/stable package.

Recompiling Nginx

You shouldn’t have to uninstall Nginx if it’s already installed before proceeding. However, it would be a good idea to back up your configuration files.

In the unlikely scenario that your own compiled version of Nginx doesn’t work quite right, just remove Nginx with APT and reinstall the repository’s version.

apt-get remove nginx
apt-get install nginx

Avoid using purge unless you want to delete any Nginx configuration files as well.

Back Up Nginx Configuration Files

# Entire configuration directory
cp -r /etc/nginx ~/nginx.bak

# Just site configurations
cp -r /etc/nginx/sites-available ~/sites-available.bak

Add Nginx Repository

Add the repository for your Nginx package. If you’d rather use the development version just replace stable with mainline. The -s allows downloading of the source packages from the repository.

If you’ve already added the repository you can also just uncomment the deb-src line in the corresponding apt sources file. For example, the stable version on Ubuntu 14.04 is /etc/apt/sources.list.d/nginx-stable-trusty.list.

sudo add-apt-repository -s -y ppa:nginx/stable
sudo apt-get update

Build Dependencies and Download Package Source

sudo apt-get -y build-dep nginx
sudo mkdir -p /opt/nginx
chown USER:USER /opt/nginx
cd /opt/nginx
apt-get source nginx

Your directory should now contain the Nginx source files. As of today the stable version of Nginx is 1.6.2 and PageSpeed is If you’re using a different versions, just replace numbers.

Nginx Module Source and Configuration Options

Download the source for the modules to be added to Nginx. In this installation the PageSpeed source is being placed within the modules directory of the Nginx package but it can be placed outside of the package source as well.

cd nginx-1.6.2/debian/modules
unzip release-${NPS_VERSION}
cd ngx_pagespeed-release-${NPS_VERSION}-beta/
tar -xzvf ${NPS_VERSION}.tar.gz  # extracts to psol/

The source for nginx-cache-purge 2.1 is already included in our Nginx package’s module directory. This older version is sufficient unless you’re compiling it with Nginx 1.7.8+ or are using Solaris with SunCC (Solaris Studio).

Add Modules to Configure Flags

Now that you have the source for Nginx and any desired modules (in this case PageSpeed), update configure flags for your desired package flavor in /opt/nginx/nginx-1.6.2/debian/rules. If you’re unsure, full is good option. Look for a block similar to the following.

full_configure_flags := \
                        $(common_configure_flags) \
                        --with-http_addition_module \
                        --with-http_dav_module \
                        --with-http_geoip_module \
                        --with-http_gzip_static_module \
                        --with-http_image_filter_module \
                        --with-http_spdy_module \
                        --with-http_sub_module \
                        --with-http_xslt_module \
                        --with-mail \
                        --with-mail_ssl_module \
                        --add-module=$(MODULESDIR)/nginx-auth-pam \
                        --add-module=$(MODULESDIR)/nginx-dav-ext-module \
                        --add-module=$(MODULESDIR)/nginx-echo \
                        --add-module=$(MODULESDIR)/nginx-upstream-fair \
                        --add-module=$(MODULESDIR)/ngx_http_substitutions_filter_module \
                        --add-module=$(MODULESDIR)/ngx_pagespeed-release- \

The new modules were added at the end of the flag block with lines broken by backslashes \. To remove a module, take out the corresponding line. When you’re doing making changes, save the file and you’re ready to compile.

The source for nginx-cache-purge was included in the Nginx package source so just add the line.

Recompile Nginx Package

cd /opt/nginx/nginx-1.6.2
dpkg-buildpackage -b

After a few minutes, the build will be complete. Go up one directory and you’ll see a number of new deb files that can be used for installation. Find the file for your Nginx flavor without dbg in the name as those are debug files.

Install New Nginx Package

# To install Nginx 
sudo dpkg -i nginx-full_1.6.2-5+trusty0_amd64.deb

# To install configuration files, documentation, and Nginx.
sudo dpkg -i nginx_*_all.deb nginx-common_*_all.deb nginx-doc_*_all.deb nginx-full_*_amd64.deb

Check Nginx Configuration Options

Check your Nginx version and configuration options to confirm addition.

$ nginx -V
nginx version: nginx/1.6.2
TLS SNI support enabled
configure arguments: --with-cc-opt='-g -O2 -fstack-protector --param=ssp-buffer-size=4

Test PageSpeed Module

Now create a cache directory and enable PageSpeed.

sudo mkdir -p /var/cache/pagespeed
sudo chown www-data:www-data /var/cache/pagespeed

Enable PageSpeed in Nginx Configuration

Add the following lines to either the HTTP or server block and then restart Nginx.

pagespeed on;
pagespeed FileCachePath /var/cache/pagespeed;

Verify Site Headers

Check your site’s HTTP headers to ensure PageSpeed is enabled.

curl -D- | less

The response headers should look similar to this. If you don’t see a X-Page-Speed header, this means that your webserver isn’t letting PageSpeed run.

Server: nginx
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Encoding
X-Powered-By: PHP/5.5.9-1ubuntu4.6
Pragma: public
Strict-Transport-Security: max-age=31536000
X-UA-Compatible: IE=Edge
Date: Sat, 07 Mar 2015 11:35:21 GMT
Cache-Control: max-age=0, no-cache

Hold Nginx Packages

If the installation looks good, you can put the Nginx packages on hold so they’re not accidentally overwritten in an upgrade.

sudo apt-mark hold nginx nginx-common nginx-doc

PageSpeed Module Configuration

For troubleshooting and configuration options, take a look at the PageSpeed Module documentation on Google Developers.

8 responses to “Adding PageSpeed and other Nginx modules on Ubuntu”

  1. Hi,

    I on Ubuntu 12.04.5 LTS.
    After update nginx is 1.8.0 .. but can’t install pagespeed .. i get:
    root@vps:/usr/src/pagespeed/nginx-1.8.0# dpkg-buildpackage -b
    dpkg-buildpackage: source package nginx
    dpkg-buildpackage: source version 1.8.0-1+precise1
    dpkg-buildpackage: source changed by Thomas Ward
    dpkg-buildpackage: host architecture amd64
    dpkg-source –before-build nginx-1.8.0
    dpkg-checkbuilddeps: Unmet build dependencies: libgd2-noxpm-dev
    dpkg-buildpackage: warning: Build dependencies/conflicts unsatisfied; aborting.
    dpkg-buildpackage: warning: (Use -d flag to override.)

    if i try to install libgd2-noxpm-dev or libgd2-noxpm — they want to remove libgd2-xpm-dev and libgd2-xpm-dev, and php5-gd .. roundcube and some other packeges ..
    i don’t want to loose gd and rouncube ..

    Any ideas?
    Thanks in advance,

  2. Hello, Tihomir!

    There seem to be a number of ways this could happen and corresponding ways to fix them. I haven’t tried this method with Nginx 1.8.0, but I will try to soon.

    There are suggestions specific to PPA dependency issues, such as make sure you’ve updated your source list and upgrade your packages with apt-get update and apt-get upgrade. Ubuntu’s apt-get documentation suggests running apt-get -f install to fix broken dependencies.

    I’d suggest trying that, and then starting the process from scratch.

  3. Hi James,

    nice article! Maybe you can help me with one issue.
    I rebuilt nginx with pagespeed and moved from v 1.6.2 to 1.8.0
    If I hit “nginx -V” it shows the old settings including the old version number.
    However, when checking page headers, it tells my that it’s running version 1.8.0.
    Any idea what I missed?

    Thanks in advance!


    • Did you check to see if you perhaps had two separate Nginx installations going? That’s my guess. However, the stable PPA recently
      upgraded version 1.8.0 as well

      jb@lemp:~$ ps -aux |grep nginx
      root 1065 0.0 0.2 106836 2580 ? Ss Jun15 0:00 nginx: master process /usr/sbin/nginx -g daemon on; master_process on;
      www-data 1069 0.0 0.9 111544 9716 ? S Jun15 0:45 nginx: worker process
      jb 10091 0.0 0.0 11740 936 pts/0 S+ 22:31 0:00 grep --color=auto nginx

      jb@lemp:~$ nginx -V
      nginx version: nginx/1.8.0
      built with OpenSSL 1.0.1f 6 Jan 2014
      TLS SNI support enabled
      configure arguments: --with-cc-opt='-g -O2 -fPIE -fstack-protector --param=ssp-buffer-size=4 -Wformat -Werror=format-security -D_FORTIFY_SOURCE=2' --with-ld-opt='-Wl,-Bsymbolic-functions -fPIE -pie -Wl,-z,relro -Wl,-z,now' --prefix=/usr/share/nginx --conf-path=/etc/nginx/nginx.conf --http-log-path=/var/log/nginx/access.log --error-log-path=/var/log/nginx/error.log --lock-path=/var/lock/nginx.lock --pid-path=/run/ --http-client-body-temp-path=/var/lib/nginx/body --http-fastcgi-temp-path=/var/lib/nginx/fastcgi --http-proxy-temp-path=/var/lib/nginx/proxy --http-scgi-temp-path=/var/lib/nginx/scgi --http-uwsgi-temp-path=/var/lib/nginx/uwsgi --with-debug --with-pcre-jit --with-ipv6 --with-http_ssl_module --with-http_stub_status_module --with-http_realip_module --with-http_auth_request_module --with-http_addition_module --with-http_dav_module --with-http_geoip_module --with-http_gunzip_module --with-http_gzip_static_module --with-http_image_filter_module --with-http_spdy_module --with-http_sub_module --with-http_xslt_module --with-mail --with-mail_ssl_module --add-module=/build/buildd/nginx-1.8.0/debian/modules/nginx-auth-pam --add-module=/build/buildd/nginx-1.8.0/debian/modules/nginx-dav-ext-module --add-module=/build/buildd/nginx-1.8.0/debian/modules/nginx-echo --add-module=/build/buildd/nginx-1.8.0/debian/modules/nginx-upstream-fair --add-module=/build/buildd/nginx-1.8.0/debian/modules/ngx_http_substitutions_filter_module

  4. I find the guide very useful! Only problem that I’m facing is that I fail to configure nginx daemon to start after system restart. Could you please advise ?

Leave a Reply

Your email address will not be published. Required fields are marked *