Adding nginx modules on Linux

When nginx is installed through the OS package manager, there is no way to add or remove modules — it comes with a fixed build configuration. To include a custom module, nginx must be rebuilt manually from source.

Step 1. Get the current nginx configuration

Run the following command and save the output to a text editor — you'll need it during the configure step:

nginx -V

Example output:

nginx version: nginx/1.12.1
built by gcc 4.8.5 20150623 (Red Hat 4.8.5-11) (GCC)
configure arguments: --prefix=/etc/nginx --conf-path=/etc/nginx/nginx.conf
--error-log-path=/var/log/nginx/error.log ...

In this example, version 1.12.1 is installed — download the same version in the next step.

Step 2. Download the nginx source

wget http://nginx.org/download/nginx-1.12.1.tar.gz

Extract the archive and enter the source directory:

tar -xvf nginx-1.12.1.tar.gz
cd nginx-1.12.1

Step 3. Install the PageSpeed module

bash <(curl -f -L -sS https://ngxpagespeed.com/install) \
     --nginx-version $nginxversion

Save all modules:

bash <(curl -f -L -sS https://ngxpagespeed.com/install) -m

Step 4. Configure nginx with the new module

From the saved nginx -V output, copy the configure arguments starting from --prefix= up to (but not including) the first --add-module= — any existing --add-module= entries are not needed.

Run ./configure with those arguments and append --add-dynamic-module=/root/incubator-pagespeed-ngx-latest-stable at the end:

./configure --prefix=/etc/nginx --conf-path=/etc/nginx/nginx.conf \
--error-log-path=/var/log/nginx/error.log \
--http-client-body-temp-path=/var/lib/nginx/body \
--http-fastcgi-temp-path=/var/lib/nginx/fastcgi \
--http-log-path=/var/log/nginx/access.log \
--http-proxy-temp-path=/var/lib/nginx/proxy \
--lock-path=/var/lock/nginx.lock \
--pid-path=/var/run/nginx.pid \
--with-pcre-jit --with-http_gzip_static_module \
--with-http_ssl_module --with-ipv6 \
--without-http_browser_module --with-http_geoip_module \
--without-http_memcached_module --without-http_referer_module \
--without-http_scgi_module --without-http_split_clients_module \
--with-http_stub_status_module --without-http_ssi_module \
--without-http_userid_module --without-http_uwsgi_module \
--add-dynamic-module=/root/incubator-pagespeed-ngx-latest-stable

Step 5. Build nginx

make
make install

Once the build is complete, verify that the new module is present:

/etc/nginx/sbin/nginx -V

The output should include --add-dynamic-module=/root/incubator-pagespeed-ngx-latest-stable.

Step 6. Replace the nginx binary

Stop nginx:

service nginx stop

Rename the current binary as a fallback:

mv /usr/sbin/nginx /usr/sbin/nginx_back

Move the newly built binary into place:

mv /etc/nginx/sbin/nginx /usr/sbin/nginx

Remove the now-unnecessary directory:

rm -rf /etc/nginx/sbin

Verify that the new binary is in use:

nginx -V

The output should include --add-dynamic-module=/root/incubator-pagespeed-ngx-latest-stable.

Start nginx:

service nginx start

Clean up the source directory:

cd ../
rm -rf nginx-1.12.1