Setting up a NGINX Server with Custom Modules on Mac OS X Using Vagrant

Daniel Korn
Aug 27, 2017 · 4 min read

It has been a few years since I last played with NGINX.
This, together with the fact that my recent move to a new startup included a change of dev environment, Linux (fedora) to Mac OS X, made the task mentioned above a little more challenging.

I was working on a POC which required setting up NGINX as a reverse proxy, with Modules not included by default.
There are two ways to install NGINX Open Source:

  • From a pre-built package: includes most NGINX official modules; can be installed on Mac OS X with homebrew: $ brew install nginx
  • Compiled from the sources: the way to add particular modules including 3rd party modules or apply latest security patches.

From this point on, I’ll focus on the latter - NGINX compiled from sources with custom modules.

In order to compile the sources, we need to run a Linux box, preferably in a lightweight virtualization provider with command line interface.
Why not just use docker? Well, TBH our R&D consists of intensive Vagrant users, and I wanted them to have one less thing to worry about when testing my POC.

Vagrant is a tool for building and managing virtual machine environments in a single workflow.

First, we’ll need to install Vagrant

$ brew cask install virtualbox vagrant

Then, we’ll create our Linux box using Vagrant

$ mkdir nginx
$ cd nginx
$ vagrant init hashicorp/precise32

The output of the last command should look like this:

A `Vagrantfile` has been placed in this directory. You are now
ready to `vagrant up` your first virtual environment! Please read
the comments in the Vagrantfile as well as documentation on
`vagrantup.com` for more information on using Vagrant.

At this point, you might want to edit the Vagranfile to allow advanced features and configurations. For example, I often create port forwarding to allow access from the host to the virtual machine.

The final steps concerning Vagrant are starting the machine and ssh into it

$ vagrant up
$ vagrant ssh

To compile NGINX from the sources, we first need to install its dependencies: PCRE, zlib and OpenSSL.

$ sudo apt-get update
$ sudo apt-get install libpcre3-dev zlib1g-dev libssl-dev

Of course, it is also possible to download their tarballs and compile them.

Once you feel comfortable enough with Vagrant, the cool kids tend to instruct Vagrant to use a shell provisioner. Simply put, this is a shell script with all of the commands we want to be executed on provision (in our case, install the dependencies and even NGINX itself). To use it, just create the script with your desired tasks in the same exact directory as the Vagrantfile and add the highlighted line to it:

Vagrant.configure(2) do |config|
config.vm.box = “hashicorp/precise32”
config.vm.provision “shell”, path: “provision.sh”
end

We now want to download and unpack the NGINX source files

$ wget http://nginx.org/download/nginx-1.13.4.tar.gz 
$ tar zxf nginx-1.13.4.tar.gz
$ cd nginx-1.13.4

After completing the previous steps we are finally ready to configure the build options. To do so we use the ./configure script that sets up various NGINX parameters, including paths to source and configuration files, compiler options, connection processing methods and the list of modules. The script ends up with creation of the Makefile required to compile the code and install NGINX.

There are 3 types of modules in NGINX, each configured differently:

  1. Modules built by default - can be disabled by including them in the configure script with the --without- prefix.
    Usage example: $ ./configure --without-http_empty_gif_module
  2. Modules not built by default - can be enabled manually by adding the --with- prefix to the configure script.
    Usage example: $ ./configure --with-http_auth_request_module
  3. Third party modules- NGINX functionality can be extended by compiling with your own module or a third-party module. Some third-party modules are listed here.
    Adding third party modules, as well as some of the modules not built by default, can be done statically or dynamically.
  • Statically linked modules - built into NGINX at compile time and are linked to the NGINX binary statically. Can be disabled only after NGINX recompilation. To compile specify the --add-module= option in the configure script and type in the path to the module:
$  ./configure ... --add-module=/usr/build/nginx-rtmp-module
  • Dynamically linked modules - compile as a shared object (*.so file) and then dynamically load into NGINX at runtime. The modules can then be loaded or unloaded at any time with the load_module directive in the NGINX configuration file. To compile specify the --add-dynamic-module= configure option in the configure script and provide the path to the module:
$  ./configure ... --add-dynamic-module=/path/to/module

To complete the installation all we need is to compile and install the build:

$ make
$ sudo make install

To verify that your NGINX is compiled with your custom module configuration, run this command and check if the output contains the expected module name:

sudo /usr/local/nginx/sbin/nginx -V2>&1 | grep -- 'http_auth_request_module'

Once the installation is finished, run NGINX

$ sudo /usr/local/nginx/sbin/nginx

It’s worth mentioning a pretty common action - editing the NGINX configuration file, which can be found in /usr/local/nginx/conf/nginx.conf by default. Just remember to reload and restart NGINX to see your changes.


Thanks to Oded David for his help with the NGINX heavy lifting.

For (almost) daily “Today I Learned” coding tips n tricks checkout my website.

)

Daniel Korn

Written by

Software Developer; Engineering Team Lead at BigPanda 🐼 You’re only as good as your last commit. https://twitter.com/korndaniel1 https://danielkorn.io/

BigPanda Engineering

The most awesome technical posts, by BigPanda engineers for engineers

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade