Setting up dnsmasq

This article wasn't updated in the last 4 years. Please double check if the content is still up-to-date.

If you find any error, please send me a quick heads-up.

This guide explains how set up that all *.test domains point to your local machine.

We use .test instead of .dev (acquired by Google) and .local (has weird resolver issues in macOS and is therefore really slow).

First install dnsmasq:

brew install dnsmasq

(you should install it as service, see below for details)

Now edit the config file in /opt/homebrew/etc/dnsmasq.conf and add the following at the end of the line:

local=/test/
address=/test/127.0.0.1

If you are on older MacBooks (pre-M1), the proper path to the config file is /usr/local/etc/dnsmasq.conf

This tells dnsmasq to resolve the .test TLD to your local machine.

Now we only need to tell macOS, that for resolving .test requests, it should use dnsmasq. So we create the config in /etc/resolver/test (you need to create the directory if it doesn’t exist. Creating the dir and editing the file requires sudo):

nameserver 127.0.0.1

The file name of the file always matches the TLD it should be used for. As soon as the file is created, macOS automatically updates and now resolves the TLD correctly.

Now restart dnsmasq:

sudo brew services restart dnsmasq

Important: normally you should never run services as root, as otherwise a bunch of config files get owned by root. This means, from now on you always need to run them as root, which is insecure and really uncomfortable. The exception to this rule is dnsmasq.

Creating a self-signed certificate

Now we create a self-signed (but trusted) certificate for all *.test domains.

First install mkcert via homebrew:

brew install mkcert
mkcert -install

Create certficate

Now create the certificate. In this example we create a certificate for localhost, current.test and *.current.test:

mkcert current.test "*.current.test" localhost 127.0.0.1 ::1
mkdir /usr/local/etc/pki/_.current.test && mv "$(mkcert -CAROOT)"/current.test* /usr/local/etc/pki/_.current.test

Installation in nginx

First get the file paths for the just created certificates:

ls -lA /usr/local/etc/pki/_current.test

Then add these files in nginx:

server {
    # ...
    listen 443 ssl http2;

    ssl_certificate     /usr/local/etc/pki/_.current.test/current.test+4.pem;
    ssl_certificate_key /usr/local/etc/pki/_.current.test/current.test+4-key.pem;
}

(keep in mind that the number in the file name can differ in your case)