Hi there.
Setting up local domains can be a serious pain. In this article, I will be providing insights into the process I have taken to set up domains and sub-domains locally using Nginx on MacOs (BigSur).
Step 1 - Edit your hosts file
On your terminal, open your hosts file in an editor of your choice.
If you have Vscode, you can run
sudo code /etc/hosts
For sublime text,
sudo subl /etc/hosts
For nano,
sudo nano /etc/hosts
For vi/vim
sudo vi /etc/hosts
The reason for adding sudo is to ensure you are able to save after your edit.
Your hosts file should look like this,
##
# Host Database
#
# localhost is used to configure the loopback interface
# when the system is booting. Do not change this entry.
##
127.0.0.1 localhost
255.255.255.255 broadcasthost
::1 localhost
Now, you need to update the file with the domain and sub-domain you require. For this article, we will be adding example.test as the main domain and index.example.test as the sub-domain. Both should be pointing to the loopback address 127.0.0.1.
After edit, we should have this,
##
# Host Database
#
# localhost is used to configure the loopback interface
# when the system is booting. Do not change this entry.
##
127.0.0.1 localhost
255.255.255.255 broadcasthost
::1 localhost
127.0.0.1 example.test # Update here
127.0.0.1 index.example.test # Update here
You can save and move to next step.
Step 2 - Download and Install Nginx
To download and install Nginx, you can run the command
brew install nginx
For further instructions on installation, you can view the brew formulae formulae.brew.sh/formula/nginx .
Note the path to your nginx installation, so as to be able to locate the nginx configuration. In my case, the path to my nginx configuration exists at /opt/homebrew/etc/nginx/nginx.conf
After successful installation, you can move to the next step.
Step 3 - Edit your Nginx configuration
To open the nginx configuration for edit, I use vscode,
code /opt/homebrew/etc/nginx/nginx.conf
It should look like this,
#user nobody;
worker_processes 1;
#error_log logs/error.log;
#error_log logs/error.log notice;
#error_log logs/error.log info;
#pid logs/nginx.pid;
events {
worker_connections 1024;
}
http {
include mime.types;
default_type application/octet-stream;
#log_format main '$remote_addr - $remote_user [$time_local] "$request" '
# '$status $body_bytes_sent "$http_referer" '
# '"$http_user_agent" "$http_x_forwarded_for"';
#access_log logs/access.log main;
sendfile on;
#tcp_nopush on;
#keepalive_timeout 0;
keepalive_timeout 65;
#gzip on;
server {
listen 8080;
server_name localhost;
#charset koi8-r;
#access_log logs/host.access.log main;
location / {
root html;
index index.html index.htm;
}
#error_page 404 /404.html;
# redirect server error pages to the static page /50x.html
#
error_page 500 502 503 504 /50x.html;
location = /50x.html {
root html;
}
# proxy the PHP scripts to Apache listening on 127.0.0.1:80
#
#location ~ \.php$ {
# proxy_pass http://127.0.0.1;
#}
# pass the PHP scripts to FastCGI server listening on 127.0.0.1:9000
#
#location ~ \.php$ {
# root html;
# fastcgi_pass 127.0.0.1:9000;
# fastcgi_index index.php;
# fastcgi_param SCRIPT_FILENAME /scripts$fastcgi_script_name;
# include fastcgi_params;
#}
# deny access to .htaccess files, if Apache's document root
# concurs with nginx's one
#
#location ~ /\.ht {
# deny all;
#}
}
# another virtual host using mix of IP-, name-, and port-based configuration
#
#server {
# listen 8000;
# listen somename:8080;
# server_name somename alias another.alias;
# location / {
# root html;
# index index.html index.htm;
# }
#}
# HTTPS server
#
#server {
# listen 443 ssl;
# server_name localhost;
# ssl_certificate cert.pem;
# ssl_certificate_key cert.key;
# ssl_session_cache shared:SSL:1m;
# ssl_session_timeout 5m;
# ssl_ciphers HIGH:!aNULL:!MD5;
# ssl_prefer_server_ciphers on;
# location / {
# root html;
# index index.html index.htm;
# }
#}
include servers/*;
}
The following should be included in nginx.conf
server {
listen 80;
listen [ :: ]:80;
server_name example.test *.example.test;
access_log /var/log/nginx/example.test.access.log;
error_log /var/log/nginx/example.test.error.log;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
}
server {
listen 80;
listen [ :: ]:80;
server_name index.example.test;
access_log /var/log/nginx/example.test.access.log;
error_log /var/log/nginx/example.test.error.log;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
}
NOTE: the proxy_pass should refer to the port your project is running on. In my case, my project is running on port 8000.
In this case, my domain and sub-domain are pointing to the same project. This means the project handles the route redirection based on the domain. But if for your project the domain and sub-domain run on separate ports, then you should configure the proxy_pass with the correct port number.
The final nginx.conf should look like this,
#user nobody;
worker_processes 1;
#error_log logs/error.log;
#error_log logs/error.log notice;
#error_log logs/error.log info;
#pid logs/nginx.pid;
events {
worker_connections 1024;
}
http {
include mime.types;
default_type application/octet-stream;
#log_format main '$remote_addr - $remote_user [$time_local] "$request" '
# '$status $body_bytes_sent "$http_referer" '
# '"$http_user_agent" "$http_x_forwarded_for"';
#access_log logs/access.log main;
sendfile on;
#tcp_nopush on;
#keepalive_timeout 0;
keepalive_timeout 65;
#gzip on;
server {
listen 8080;
server_name localhost;
#charset koi8-r;
#access_log logs/host.access.log main;
location / {
root html;
index index.html index.htm;
}
#error_page 404 /404.html;
# redirect server error pages to the static page /50x.html
#
error_page 500 502 503 504 /50x.html;
location = /50x.html {
root html;
}
# proxy the PHP scripts to Apache listening on 127.0.0.1:80
#
#location ~ \.php$ {
# proxy_pass http://127.0.0.1;
#}
# pass the PHP scripts to FastCGI server listening on 127.0.0.1:9000
#
#location ~ \.php$ {
# root html;
# fastcgi_pass 127.0.0.1:9000;
# fastcgi_index index.php;
# fastcgi_param SCRIPT_FILENAME /scripts$fastcgi_script_name;
# include fastcgi_params;
#}
# deny access to .htaccess files, if Apache's document root
# concurs with nginx's one
#
#location ~ /\.ht {
# deny all;
#}
}
server {
listen 80;
listen [ :: ]:80;
server_name example.test *.example.test;
access_log /var/log/nginx/example.test.access.log;
error_log /var/log/nginx/example.test.error.log;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
}
server {
listen 80;
listen [ :: ]:80;
server_name index.example.test;
access_log /var/log/nginx/example.test.access.log;
error_log /var/log/nginx/example.test.error.log;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
}
# another virtual host using mix of IP-, name-, and port-based configuration
#
#server {
# listen 8000;
# listen somename:8080;
# server_name somename alias another.alias;
# location / {
# root html;
# index index.html index.htm;
# }
#}
# HTTPS server
#
#server {
# listen 443 ssl;
# server_name localhost;
# ssl_certificate cert.pem;
# ssl_certificate_key cert.key;
# ssl_session_cache shared:SSL:1m;
# ssl_session_timeout 5m;
# ssl_ciphers HIGH:!aNULL:!MD5;
# ssl_prefer_server_ciphers on;
# location / {
# root html;
# index index.html index.htm;
# }
#}
include servers/*;
}
Step 4 - Create log folder
A common cause for error when working with this is that there may not be an nginx folder under the /var/log/ path. To create the folder, you can run
mkdir /var/log/nginx
Step 5 - Start up Nginx
Before we startup Nginx, from my experience, it is better to have the nginx property list file in the ~/Library/LaunchDaemons folder, but default you'd have it in the ~/Library/LaunchAgents folder, hence we need to move it, with the following command
sudo mv ~/Library/LaunchAgents/homebrew.mxcl.nginx.plist /Library/LaunchDaemons/
Then, modify the file permissions to allow loading
sudo chown root:wheel /Library/LaunchDaemons/homebrew.mxcl.nginx.plist
Finally, load the plist file to startup nginx,
sudo launchctl load -w /Library/LaunchDaemons/homebrew.mxcl.nginx.plist
To confirm nginx has started you should run,
sudo brew services list
A successfully started nginx response should look like this,
Name Status User File
nginx started root /Library/LaunchDaemons/homebrew.mxcl.nginx.plist
If the Status show error you can run nginx -T to test your configuration file and check if there are any errors.
Step 6 - Test your setup
Now you can startup your project on the port you have defined in the nginx.conf proxy_pass.
And open up your browser and visit your url at http://example.test.
You should see your project come up!
That's it!
Feel free to comment below if this setup works or doesn't work for you.
I'll see you in the comments.
Cheers!