Dealing with local HTTPS development

When developing web applications, specific scenarios demand HTTPS, even in a local environment. Whether you're integrating with secure third-party APIs, testing HTTPS-only features like service workers and HTTP/2, or replicating production conditions to ensure seamless deployment, HTTPS becomes crucial. Additionally, certain browser APIs—such as geolocation, push notifications, and credentials management—require a secure context to operate effectively.

For example, Logto OSS requires HTTPS by default expect localhost, in such cases, learning about setting up HTTPS for local development can save your time. This article will guide you through the setup of HTTPS for local development, introducing tools like Mkcert to simplify the process.

The role of localhost and HTTPS-only features#

localhost is a special domain that can handle many HTTPS-only functionalities like service workers, secure cookies, HTTP/2 and other browser APIs can work well in http://localhost:xxxx, so you may not always need local HTTPS, try localhost first!

Try Cloudflare tunnels#

Previously introduced in this article, Cloudflare tunnels can easily expose your local service to the Internet with HTTPS ready.

Setting up local HTTPS#

The 2 options can not solve you problem? Then let's set up local HTTPs. In the following steps, we assume that the local domain name is example.com.

Step 1: update hosts file#

Before we start, make sure the target domain resolvs to you local machine, this can be done by updating the hosts file. Open /etc/hosts on Linux/macOS or C:\Windows\System32\drivers\etc\hosts on Windows, and add the following lines:

Step 2: generate certificates#

The first thing about HTTPS is a certifcation. In production, this can be done by tools like "Let's encrypt" or buy certs from your service providers. But in local development, we can generate certs directly.

Mkcert is a simple zero-config tool to make locally trusted development certificates with any names you'd like.

First, follow the offical guide to install mkcert, assuming you are using macOS:

For Windows and Linux, check out this link.

Now with mkcert ready to use, run this command to generate a local CA and store the root certificate in your system trust store. To learn more about "CA" and certificates, check out the documentation by Cloudflare.

Then, generate a local SSL certificate

This creates example.com.pem and example.com-key.pem files in your directory.

Step 3: setup HTTPS in your app#

With certificate files ready, you can now enable HTTPS in your app. Unlike in production environment where a reverse proxy like Nginx handles the HTTPS, in local development, we can set up directly in the web applications. Let's take Express as an example.

Create a simple Express server with the following code:

Run the application, and visit https://example.com to see your secure Express app in action.

Enable HTTPS for Logto OSS#

Logto OSS requires HTTPS by default, expect for localhost, if you want to run Logto locally with other domain, you'll need to set up local HTTPS.

1. Set up Logto: Follow the link to set up Logto in your local machine: https://docs.logto.io/docs/get-started/.
2. Prepare certificates: Use mkcert to generate two .pem files and place them in a directory.
3. Set env variables: Provide both HTTPS_CERT_PATH and HTTPS_KEY_PATH to enable HTTPS via Node, check this link to learn more.

Summary#

Setting up HTTPS for local development isn’t as complicated as it might seem. With the help of tools like Mkcert, generating trusted local certificates becomes a quick and easy process. While localhostBold often handles many HTTPS-only features, there are times when you need full HTTPS support, and this guide helps you get there. Whether you’re testing APIs, working with Logto OSS, or simply replicating production conditions, following these steps will ensure you’re ready for secure, seamless development.