1. Development

Prerequisites

A C compiler must be installed that meets the ISO C Standard (C99), such as gcc.
On macOS, the C compiler installed by XCode works fine.

1. Install an IDE

This project can be developed in a basic manner with Visual Studio Code and the C/C++ Extension Pack.
Alternatively, a more specialist compiler such as CLion can be used, with better debugging features.

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-3.3.2' ./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 in CLion, then 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"
}