Installing NGINX with Custom Modules on macOS

NGINX is a high-performance, feature-rich web server and reverse proxy. The standard Homebrew NGINX installation (brew install nginx) provides core functionality, but sometimes we need additional modules that aren't compiled in by default, such as headers-more-module, rtmp-module, and others.

Fortunately, there's a Homebrew tap designed specifically for this purpose: denji/homebrew-nginx. This tap allows us to install a version of NGINX called nginx-full, with the flexibility to compile in many extra modules.

This blog post will guide you through using this tap to install and manage a highly customized NGINX setup on your Mac.

Why Custom Modules?

Enhanced Functionality: For example, the headers-more-module allows for more flexible manipulation (adding, setting, or clearing) of HTTP headers.
Specific Needs: A streaming server might require the rtmp-module.
Performance Optimization: Certain modules can offer performance benefits in specific scenarios, like brotli for better compression.
Security: Modules like brotli (also for security through efficient compression) or other security-focused modules.

Installation Steps

1. Add the Tap

First, you need to add the denji/nginx tap to your Homebrew. Taps are sources for third-party software repositories.

brew tap denji/nginx

This command downloads the tap's metadata, giving you access to its formulae (package definitions).

2. Explore Available NGINX Modules

Before installing nginx-full, you might want to see which module options are available. You can do this with:

brew options nginx-full

Or for more detailed information:

brew info nginx-full

This will list all the compilation options in the format --with-xxx-module, for example:

--with-accept-language-module
--with-accesskey-module
--with-addition-module
--with-akka-http-module
--with-auth-digest-module
--with-auth-ldap-module
--with-auth-pam-module
--with-auto-cert-module
--with-brotli-module
--with-cache-purge-module
--with-captcha-module
--with-debug
--with-dav-ext-module
--with-echo-module
--with-fancyindex-module
--with-flv-module
--with-geoip-module
--with-geoip2-module
--with-gunzip-module
--with-gzip-static-module
--with-headers-more-module
--with-http2-module
--with-http2-dynamic-module
...and many more

3. Install `nginx-full` with Desired Modules

Now you can install nginx-full and specify the modules you need. For instance, if we want to install headers-more-module and brotli-module:

brew install nginx-full --with-headers-more-module --with-brotli-module

Homebrew will download the NGINX source code and the source code for your selected modules, then compile them. This process might take a few minutes.

If you don't need any extra modules beyond what denji's nginx-full offers by default (which might already include more modules than the official core NGINX), you can simply run:

brew install nginx-full

4. Handling Conflicts with Official NGINX

If you've previously installed the official Homebrew NGINX via brew install nginx, you now have two NGINX versions on your system: nginx (official) and nginx-full (from denji).

They cannot both be "linked" at the same time (i.e., their binaries cannot simultaneously be linked to paths like /usr/local/bin or /opt/homebrew/bin, causing the nginx command to point to them).

You need to decide which one to use. To switch to nginx-full:

Unlink the current NGINX (if installed and linked):
```
brew unlink nginx
```
If nginx isn't linked, this command might inform you it's not linked, which is fine.
Link nginx-full:
```
brew link nginx-full
```
This command links the nginx-full executables into your PATH. Now, when you type the nginx command in your terminal, it will run nginx-full.

At this point, you can use standard NGINX commands, such as checking the configuration or reloading:

nginx -t       # Test configuration
nginx -s reload # Reload configuration

5. Starting and Managing the NGINX Service

Using Homebrew services to manage the NGINX service is good practice, as it allows NGINX to start automatically on boot.

Key Point: Since we installed nginx-full, we must also use the name nginx-full when starting the service.

Start the nginx-full service:
```
brew services start nginx-full
```
If this command is successful, you should be able to see the NGINX welcome page by visiting http://localhost:8080 (NGINX's default port).

Stop the nginx-full service:

brew services stop nginx-full

Restart the nginx-full service:

brew services restart nginx-full

Check service status:
```
brew services list
```
You should see nginx-full with a status of started.

Note: If you try to run brew services start nginx while nginx-full is currently linked, this command will likely fail or not start the service you intend, as service management is based on the formula name.

6. Verify Installed Modules

After installation, you can check NGINX's version information and the modules it was compiled with using the nginx -V (uppercase V) command:

nginx -V

The output should include the modules you added via the --with-... options.

Summary

Using the denji/nginx tap, we can conveniently install a more comprehensively featured NGINX on macOS. Remember these key steps:

brew tap denji/nginx
brew install nginx-full --with-YOUR-MODULES
brew unlink nginx (if necessary)
brew link nginx-full
brew services start nginx-full

You now have a powerful, customizable NGINX environment to better suit your project needs!

If you wish to switch back to the official NGINX (assuming it's installed), the steps are similar:

brew services stop nginx-full # Stop the service first
brew unlink nginx-full
brew link nginx
brew services start nginx

Enjoy your more flexible NGINX experience!

Community

We're excited to see the community adopt Hyperse-io, raise issues, and provide feedback. Whether it's a feature request, bug report, or a project to showcase, please get involved!