Installation of NGINX in macOS (Homebrew)
NGINX (pronounced Engine-X) is a popular web server that serves websites and web applications. This article will detail how to install and configure NGINX in macOS.
macOS lacks a proper package manager. Fortunately, Homebrew does a good job filling the void of a package manager. You can find more details and installation instructions here.
Installation
With Homebrew, you can easily install NGINX as follows:
brew install nginx
Configure a site
I use dnsmasq, a DNS caching utility, to implement a local domain with the TLD .test. The local domains are for SaaS (software as a service - multi-tenancy) applications that use subdomains to differentiate between tenants (ex: tenant1.example.com, tenant2.example.com).
This is an example for site:
Create a new file under /usr/local/etc/nginx/servers/<site> and add the following details. I use NeoVIM, so it looks like:
nvim /usr/local/etc/nginx/servers/jdeen.test
upstream jdeentest {
server unix:/tmp/jdeencom.sock max_fails=3 fail_timeout=600;
}
server {
listen 80;
server_name *.jdeen.test;
root /Volumes/Dev/JDeen/Projects/JDeenCOM/jdeencom/public;
try_files $uri/index.html $uri @jdeentest;
error_log /Volumes/Dev/JDeen/Projects/JDeenCOM/jdeencom/log/nginx-error.log;
access_log /Volumes/Dev/JDeen/Projects/JDeenCOM/jdeencom/log/nginx-access.log;
location @jdeentest {
proxy_pass http://jdeentest;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $http_host;
proxy_redirect off;
}
error_page 500 502 503 504 /500.html;
client_max_body_size 4G;
keepalive_timeout 10;
}
brew services failure
I find managing NGINX services through brew (brew service) unreliable. Running the application gives me an error code 256.
⇒ brew services list
Name Status User File
mysql none
nginx error 256 root ~/Library/LaunchAgents/homebrew.mxcl.nginx.plist
postgresql started root ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist
redis started jdeen ~/Library/LaunchAgents/homebrew.mxcl.redis.plist
jdeen@iMac:/Volumes/Dev/JDeen/Projects/JDeenCOM/jdeencom|master
⇒ brew services start nginx | pbcopy
Bootstrap failed: 5: Input/output error
Try re-running the command as root for richer errors.
Error: Failure while executing; `/bin/launchctl bootstrap gui/501 /Users/jdeen/Library/LaunchAgents/homebrew.mxcl.nginx.plist` exited with 5.
Direct usage
While brew services fails to deliver results, you can use nginx directly.
sudo nginx # Start nginx
sudo nginx -s stop # Signal the main process to stop
sudo nginx -s reload # Signal the main process to reload configuration
Running nginx -help will give you a list of options at your disposal.
⇒ nginx -help
nginx version: nginx/1.23.1
Usage: nginx [-?hvVtTq] [-s signal] [-p prefix]
[-e filename] [-c filename] [-g directives]
Options:
-?,-h : this help
-v : show version and exit
-V : show version and configure options then exit
-t : test configuration and exit
-T : test configuration, dump it and exit
-q : suppress non-error messages during configuration testing
-s signal : send signal to a master process: stop, quit, reopen, reload
-p prefix : set prefix path (default: /usr/local/Cellar/nginx/1.23.1/)
-e filename : set error log file (default: /usr/local/var/log/nginx/error.log)
-c filename : set configuration file (default: /usr/local/etc/nginx/nginx.conf)
-g directives : set global directives out of configuration file
Conclusion
NGINX is a favourite among many web application development circles, especially Ruby on Rails. While macOS is also a favourite among the developer community, the use of applications intended for Linux is not always straightforward. But with a little work arround and extra steps, you can get the desired behaviour.
About the Author
Ziyan Junaideen -
Ziyan is an expert Ruby on Rails web developer with 8 years of experience specializing in SaaS applications. He spends his free time he writes blogs, drawing on his iPad, shoots photos.