How to configure the HTTPS server locally on Mac OS?

Prerequisite:

1. Mac OS ( Big Sur or Monterey )
2. Apache webserver installed via brew

This tutorial has two parts.

1. Configure the Apache virtual host.
2. Install mkcert using brew

I do not use the default macOS Apache server because it has a limitation also if we upgrade the OS It may cause issues. 

I skip the Apache installation part and directly configure the virtual host. If you want Apache server installation using brew, tell me in the comment section I will write.

Step 1: Configure the Apache virtual host. 

You can set up multiple virtual hosts for your various projects. This means that you can set up local website names such as example.test or project-x.test for a project-specific URL.

In this tutorial, I will use local.test as a domain.

Apache generally performs name-based matching, so you don’t need to configure multiple IP addresses. Detailed information can be found on the apache.org site.

Apache already comes preconfigured to support this but it is not enabled. To enable this option first open the Apache configuration file

/usr/local/etc/httpd/httpd.conf

You can edit the file using Vim or Nano Editor but here I use Visual Studio Code Editor because I can have the full power of finding and replacing over the command-line editors.

Install VSCode using the following CLI command :

brew install --cask visual-studio-code

If you already installed Visual Studio Code, you can easily create a code symlink with:

ln -s /Applications/Visual\ Studio\ Code.app/Contents/Resources/app/bin/code /usr/local/bin/code

Now open the httpd.conf file in the command line

code /usr/local/etc/httpd/httpd.conf

Find the below lines and uncomment them

# LoadModule vhost_alias_module lib/httpd/modules/mod_vhost_alias.so

# Include /usr/local/etc/httpd/extra/httpd-vhosts.conf

After uncomment it will look like below

LoadModule vhost_alias_module lib/httpd/modules/mod_vhost_alias.so
Include /usr/local/etc/httpd/extra/httpd-vhosts.conf

Edit the following file to configure the virtual host. This file already presents some instructions don’t touch that for now. When you set up virtual hosts, you will lose your older document root, so you will need to add back support for that first as a virtual host.

code /usr/local/etc/httpd/extra/httpd-vhosts.conf

<VirtualHost *:80>
    DocumentRoot "/Users/[username]/Sites"
    ServerName localhost
</VirtualHost>

Let’s add document root for local.test

<VirtualHost *:80>
    DocumentRoot "/Users/[username]/Sites/local"
    ServerName local.test
</VirtualHost>

Don’t forget to change [username] for your actual username on your Mac.

For example: DocumentRoot “/Users/kuppuraj/Sites”

Also, don’t forget to create a folder local in your document root  “/Users/[username]/Sites/”

By default local.test will not resolve to your local machine. So you can do this by manually adding entries to /etc/hosts every time, or you can install and configure Dnsmasq to automatically handle wildcard *.test names and forward all of them to localhost (127.0.0.1).

First, we install it with brew:

brew install dnsmasq

Then we set up *.test hosts:

echo 'address=/.test/127.0.0.1' > /usr/local/etc/dnsmasq.conf

Reboot automatically in the future.

sudo brew services start dnsmasq

And Finaly, add it to the resolvers:

sudo mkdir -v /etc/resolver
sudo bash -c 'echo "nameserver 127.0.0.1" > /etc/resolver/test'

Now you can test it out by pinging some bogus .test name:

ping local.test

Step 2: Install mkcert using brew

mkcert is a simple tool for making locally-trusted development certificates.

brew install mkcert

After installing

mkcert -install

You will see the following message

Now we are going to install the certificate.

Create a folder in your document root  “/Users/[username]/Sites/”

cd  /Users/[username]/Sites/
mkdir crt
cd crt

Run the following command to install the certificate

mkcert local.test

You will see the following message.

Created a new certificate valid for the following names 📜

 – “local.test”

The certificate is at “./local.test.pem” and the key at “./local.test-key.pem” ✅

It will expire on 8 July 2024

You need to load the SSL module in your Apache configuration file.

By default, it is not enabled. To enable the SSL module edit the following file 

code /usr/local/etc/httpd/httpd.conf

Find and uncomment the below line

# LoadModule ssl_module lib/httpd/modules/mod_ssl.so

Now we need to tell the certificate to Apache so again edit the following file and add extra lines to the virtual host section.

Also, change the port number 80 to 443.

code /usr/local/etc/httpd/extra/httpd-vhosts.conf

<VirtualHost *:443>
    DocumentRoot "/Users/[username]/Sites/local"
    ServerName local.test
    SSLEngine on
    SSLCertificateFile "/Users/[username]/Sites/crt/local.test.pem"
    SSLCertificateKeyFile "/Users/[username]/Sites/crt/local.test-key.pem"
    VirtualDocumentRoot /Users/[username]/Sites/local
</VirtualHost>

The most important thing is your server needs to listen 443 port so make sure it is listening.

Check this URL in the browser https://local.test. If it shows a connection refused page then add the following line on top of the below file.

/usr/local/etc/httpd/extra/httpd-vhosts.conf

Listen 443

After editing all files restart the Apache

brew services restart httpd

Now access the URL https://local.test you will see the HTTPS green mark in your browser