Build 51Degrees as an NGINX Dynamic Module

2/23/2018 1:19 PM

Device Detection NGINX Tutorial Development Device Data

In this tutorial video we show you how to build 51Degrees Device Detection as an NGINX Dynamic Module.

51Degrees are certified as an NGINX module. We thought we’d put together a video tutorial showing how you can integrate our Device Detection API into your NGINX Server. In this video we go through how to set up our device detection solution on a Linux machine using NGINX, add properties to call from the data file and finally check that the results are being returned as response headers on the site.


This video was put together by Josh, one of our engineers at 51Degrees.

In this video we will go through the initial setup, adding properties to call from the data file and finally checking that the results are being returned as response headers on the site.

We don’t cover installing NGINX but here are some guidelines on how to build it from source.

With version 1.11.5 NGINX introduced the capability to compile dynamic modules independently which is what we will be doing.

It is possible to install Device Detection using an earlier version but it’s not something we will cover in this tutorial. If you need any help you can get in touch with us.

It’s important to check you have ‘—with-compat’ available as a configure argument. You can check this by doing:

Nginx -V

From there you can see the version of NGINX you are running as well as all the configure arguments.

Downloading and building the dynamic module

The first thing you are going to need to do is download our Repository. 51Degrees is an open source product so you can get this by going to our GitHub.

git clone https://github.com/51Degrees/Device-Detection.git

Copy over your 51Degrees data file into the cloned repository.

cp path/to/51Degreesdatafile.trie Device-Detection/data

Move into the 51Degrees NGINX directory.

cd Device-Detection/nginx/

NOTE: The next few steps are not required to install as a dynamic module but is recommended as it contains tests that allow you to see any potential issues during install. You will need to edit the Makefile so that the tests are referencing the correct data file.

nano Makefile

Dependent on whether you are using Pattern or Hash Trie, change the name of the data file in code below and save.

ifeq (test,$(firstword $(MAKECMDGOALS)))
FULLPATH := $(shell pwd)
ifneq (,$(findstring TRIE,"$(shell ./nginx -V 2>&1)"))
        DATAFILE := "51Degrees-LiteV3.4.trie"
ifneq (,$(findstring PATTERN,"$(shell ./nginx -V 2>&1)"))
        DATAFILE := "51Degrees-LiteV3.2.dat"

NOTE: replace trie with pattern if using this detection method.

make install trie

make test

Now onto to building the dynamic module, replace the version in the example below with the current version of NGINX you are using.

make module trie VERSION=1.13.7

Configuring NGINX with 51Degrees

Copy the output to your NGINX directory. If you do not have a modules folder then you can just create one.

sudo cp build/modules/ngx_http_51D_module.so /path/to/nginx/prefix/modules/

Copy your data file to a location where NGINX get to it. In the video example we have created a data folder within the Prefix location.

sudo cp ../../../data/51Degreesdatafile.trie /path/to/nginx/prefix/data/

Amend your Nginx config file.

sudo nano /path/to/nginx/prefix/nginx.conf

Add a reference to your compiled dynamic module near the top of the config.

load_module modules/ngx_http_51D_module.so;

Add some settings in the config file. NOTE: The cache setting shown below is purely for Pattern.

http {

    51D_filePath /path/to/nginx/data/51Degreesdatafile.trie;
	51D_cache 10000;
	#Additional settings

Within the Location block, add in some matches and add them to return as response headers.

 location / {
            root   html;
            index  index.html index.html;

            51D_match_all x-mobile IsMobile;
            51D_match_all x-tablet IsTablet;

            add_header x-mobile $http_x_mobile;
            add_header x-tablet $http_x_tablet;

Check everything over and then save.

nginx -t

restart NGINX

sudo systemctl restart nginx

Now configuration is complete, you can connect to your web server via an Internet browser and open up the developer tools. If you reload the page when on the network tab you will be able to see the 2 matches we have created returning as response headers.

Try emulating a few different devices to see the results.

Note: If you use a tablet, x-mobile will return true as, within our data base, we count tablets as "mobile" because you can use it while you are walking down the street. if you were to call the "IsSmartphone" property instead of "IsMobile" then a tablet would return as false.

We hope you found this information helpful.

Please feel free to contact us with any question.