1. Development

Prerequisites

A C compiler must be installed that meets the ISO C Standard (C99), such as gcc.
The default compiler on macOS, or that installed by XCode, is usually fine.

1. Install an IDE

This project can be run in a basic manner with Visual Studio Code and the C/C++ Extension Pack.
When developing we recommend a more specialist tool such as CLion 2020.2 or newer.

2. OpenSSL Setup

On Docker images we build the code as a dynamic module using libssl-dev.
This package is not available for macOS so instead we build OpenSSL from source.
Development IDEs can then find OpenSSL headers in the correct system locations:

./resources/localhost/openssl_install.sh

Standard system locations will then be updated:

/usr/local/include/openssl/*
/usr/local/lib/libcrypto*
/usr/local/lib/libssl*
/usr/local/bin/openssl
/usr/local/share/man

3. Configure

Then run the base configure script as follows, to download NGINX source and use these options on macOS:

CONFIG_OPTS='--with-http_ssl_module --with-openssl=../openssl-OpenSSL_1_1_1m' ./configure

Select these options to enable Perl tests to run and to enable debugging of the C code in CLion:

DYNAMIC_MODULE=n
NGINX_DEBUG=y

4. Make

Whenever the code in the module changes, run this command to rebuild NGINX:

make

5. Make Install

Pre-creating the nginx folder for development is recommended.
This enables nginx to be run as your own user account, which works better later when debugging:

sudo mkdir /usr/local/nginx
sudo chown yourusername /usr/local/nginx

Whenever you want to update the local system after building code, do a make install.
This deploys an entire NGINX system under the /usr/local/nginx folder:

make install

6. Run NGINX Locally

Finally deploy the nginx.conf development configuration and start NGINX locally:

cp ./resources/localhost/nginx.conf /usr/local/nginx/conf/nginx.conf
/usr/local/nginx/sbin/nginx

This nginx.conf file is configured to disable the daemon, so that logs are easily viewable.

7. Debug Code

To perform printf debugging you can add ngx_log_error statements to the C code and then look at NGINX output.
Once nginx is running, select Run / Attach to Process, and choose the nginx worker process.
Then set breakpoints, after which you can step through code to check variable state carefully:

8. Act as an SPA Client

You can run curl requests against the nginx system in the same manner as the SPA:

AT_COOKIE='AcYBf995tTBVsLtQLvOuLUZXHm2c-XqP8t7SKmhBiQtzy5CAw4h_RF6rXyg6kHrvhb8x4WaLQC6h3mw6a3O3Q9A'
curl -i -X GET http://localhost:8080/api \
-H "origin: https://www.example.com" \
-H "cookie: example-at=$AT_COOKIE"

The access token received by the target API is then echoed back to the caller.
The response also includes CORS headers returned by the module:

access-control-allow-origin: https://www.example.com
access-control-allow-credentials: true

{
    "message": "API was called successfully with Bearer 42665300-efe8-419d-be52-07b53e208f46"
}