How to Run Localhost with HTTPS

By Thoriq Firdaus. in Hosting. Updated on June 13, 2024.

SSL (Secure Socket Layer) encrypts data transactions between a browser and server, enhancing the security of your website. While using HTTP for localhost is usually enough for development, sometimes you need to test it in HTTPS. For example, you may need to test a service worker, set secure cookies which need the site to load over HTTPS, or test third-party API that typically requires HTTPS such as an Auth or Payment type of APIs.

Testing your site with SSL during development ensures all elements, including URLs and resources like CSS and JavaScript, function properly under HTTPS. This helps mirror the production environment more accurately, helping in smoother transitions when going live.

In this article, we’ll guide you through the process of enabling HTTPS on your localhost, ensuring you’re prepared for any secure testing needs.

Ready to get started? Let’s go!

Getting Started with `mkcert`

mkcert simplifies the process of installing SSL certificates for localhost. Unlike the traditional methods that are often complex, mkcert offers a straightforward approach. It sets up a locally trusted development certificate by automatically installing and trusting a local Certificate Authority (CA) on your system. This tool is compatible with macOS, Linux, and Windows, covering a wide range of development environments.

If you’re on macOS or Linux, you’ll first need to install Homebrew. Windows users should install Chocolatey. With these tools in place, you can easily install mkcert by running the following commands:

// For macOS or Linux
brew install mkcert && brew install nss # "nss" is needed for Firefox support

// For Windows
choco install mkcert

Installing SSL Certs

Begin by executing the command below to create a Certificate Authority (CA) that will sign your certificates:

mkcert -install

It’s important to keep the rootCA-key.pem file secure and never share it. If compromised, an attacker could potentially intercept your secure connections to any site. Please handle this file with caution!

Following the creation of the CA, generate a certificate for the localhost hostname using this command:

mkcert localhost

This tool is also versatile enough to produce certificates for other hostnames or even local IP addresses, such as 127.0.0.1.

For instance:

mkcert hongkiat.local www.hongkiat.local 127.0.0.1

Running an HTTP Server

With your SSL certificates ready, you can now launch your local server using HTTPS. For those utilizing Node.js, the http-server package offers a straightforward method to start a server. You need to specify the paths to your certificate and key files.

For instance, here’s how to run a localhost server on port 8080:

http-server -S -C localhost.pem -K localhost-key.pem -p 8080

Once running, your localhost can be accessed via HTTPS at https://localhost:8080.

Localhost running with HTTPS on a browser

Running with Docker and Nginx

If Docker and Nginx are part of your setup, the following server configuration allows you to run HTTPS:

server {
    listen 443 ssl;
    server_name localhost;

    ssl_certificate /path/to/localhost.pem;
    ssl_certificate_key /path/to/localhost-key.pem;

    location / {
        root /var/www/html;
    }
}

Link the necessary certificates and configuration files to your Docker container through a Docker Compose configuration file, as shown below:

services:
    nginx: 
        image: nginx:latest 
        ports: 
        - "8081:443"
        volumes: 
        - ./localhost-key.pem:/etc/nginx/certs/localhost-key.pem
        - ./localhost.pem:/etc/nginx/certs/localhost.pem
        - ./nginx.conf:/etc/nginx/conf.d/default.conf
        - ./index.html:/var/www/html/index.html

Uninstall `mkcert`

If you decide to stop using HTTPS for local development or if you’re switching to another method for handling SSL certificates, you might want to uninstall mkcert.

To remove mkcert from your system, execute the following command:

mkcert -uninstall

This command deletes the root CA from both your system and browser. You should also remove the root certificate file and any certificates pairs you’ve generated:

rm -r "$(mkcert -CAROOT)"

Conclusion

Implementing HTTPS on your local server is crucial for properly testing features such as service workers, secure cookies, and third-party APIs that require a secure connection. mkcert provides an efficient way to generate and manage SSL certificates across various platforms and browsers, streamlining the process for developers.

Getting Started with mkcert