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 1.9.23.3. 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
NPS_VERSION=1.9.32.3
wget https://github.com/pagespeed/ngx_pagespeed/archive/release-${NPS_VERSION}-beta.zip
unzip release-${NPS_VERSION}-beta.zip
cd ngx_pagespeed-release-${NPS_VERSION}-beta/
wget https://dl.google.com/dl/page-speed/psol/${NPS_VERSION}.tar.gz
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-1.9.32.3-beta \
                        --add-module=$(MODULESDIR)/nginx-cache-purge

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
...
 --add-module=/opt/nginx/nginx-1.6.2/debian/modules/ngx_pagespeed-release-1.9.32.3-beta

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- https://jamesbradach.com | 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
X-Page-Speed: 1.9.32.3-4448
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.