October 21st, 2019

How to setup HTTPS (SSL) on your local development environment (localhost) in minutes

I was recently working on a mobile application that I needed HTTPS to test on my local device rather than just on the desktop. After several hours of trial and error, let me show you the easiest way to setup HTTPS on your localhost environment.

Covered in this guide:

  • (Optional) Setup local DNS masking for macOS
  • Install and setup local certificates
  • Setup a local dev server with HTTPS
    • And how to easily access it via your mobile device

Let’s begin:

1. (Optional) Setup DNS Masking for macOS

If you’re on macOS, there’s a very handy configuration setting you can setup to make it easy to access your local dev environment over your local network. It’s basically creating a custom URL that can access your device locally. Very helpful when doing mobile development work. This can be done for Windows and Linux as well, but you’ll have to figure out the steps yourself for those platforms.

In macOS (I’m using 10.14.5 so you might have a slightly different path on other versions), open up System Preferences and go to Sharing.

Then, right under where you can change your computer name, click the “Edit…” button. There, you can change your local hostname to anything you like. I like mine short and narcissistic.

Changing macOS local hostname

System Preferences > Sharing > Edit...

2. Install mkcert for cert setup

Next is to setup local certificates. This is normally the toughest part, but there’s a great tool called mkcert that makes it very simple and easy. It automatically generates and installs the SSL certificates, saving a ton of time.

Just follow the instructions on GitHub. If you’re on macOS and using Homebrew, run the following:

brew install mkcert
brew install nss # if you use Firefox

3. Generate and install HTTPS certs

With mkcert installed, let’s generate and install the SSL certs! Just run the following, modifying to whatever you set your local DNS hostname to:

mkcert localhost matthew.local ::1 # Generate the certs
mkcert -install # Install the certs into the system

What the first command does is create the certificates in the working directory. The next command is optional, but it’s a good idea to install them into the system to make it easier for future projects.

Those Certs

Hang on to the certs that you just generated (most likely named localhost.pem and localhost-key.pem). There's an optional step at the end of this guide that you will need them for.

4. (Optional) Setup iOS to use generated certs

If you happen to use an iOS device, you also need to manually setup the local cert you just created. Simply airdrop the localhost.pem file to your device and install it.

Next on your iDevice, go to Settings > General > Profile and install the airdropped certificate.

And finally, if you’re using iOS 10.3 or later (so everyone), you have to manually tell iOS to trust this certificate for HTTPS. On your iDevice, go to Settings > General > About > Certificate Trust Settings and under “Enable full trust for root certificates,” turn on trust for the certificate. More info on this can be found here.

5. (Bonus) Setup a simple local server and test your new HTTPS abilities

Now that you’re all set, let’s setup a local environment and test your new secure local connection. For an easy web server, I use http-server. It’s a very lightweight and easy to use tool to spin up a simple static server for testing projects locally. I use all the time.

Just install http-server using the link above. Then create a simple web project, say like a folder on your desktop with an index.html file. In the same folder, drop in your localhost.pem/localhost-key.pem files from earlier. Then from that folder run the following terminal command:

http-server -S -C localhost.pem -K localhost-key.pem
  • -S is for SSL
  • -C is the path for the SSL cert
  • -K is the path for the SSL key

Your server should launch, and should be accessible at https://localhost:8080 (desktop only) or https://matthew.local:8080 (desktop or devices on the same local/wireless network)!

You’re now fully setup with HTTPS on your local devices!