Set Up HTTPS for Your Local HTTP Server on macOS: A Proxy Guide

During web development, it’s common practice to serve applications via HTTP for local testing. However, modern web development, especially when working with services like Storyblok v2 or utilizing secure browser features, often requires your local development environment to operate over HTTPS. This ensures feature parity with production environments and avoids potential issues related to mixed content or secure context requirements.

This guide provides a step-by-step walkthrough on how to set up an HTTPS proxy for your local HTTP server on macOS. By using mkcert and local-ssl-proxy, you can easily create a secure development environment that mirrors production setups, ensuring a smoother development process.

Prerequisites

Before you begin, ensure you have the following prerequisites installed on your macOS system:

• Homebrew: Homebrew is a package manager for macOS, simplifying the installation of various tools. If you don’t have it installed, open your terminal and run the following command:

  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

  After installation, it’s recommended to add Homebrew to your system’s PATH environment variable. Run these commands in your terminal:

  echo "export PATH=/opt/homebrew/bin:$PATH" >> ~/.bash_profile && source ~/.bash_profile

• Node.js and npm (Node Package Manager): local-ssl-proxy is a Node.js package, so you’ll need Node.js and npm installed. Typically, npm is bundled with Node.js. You can download and install Node.js from the official Node.js website.

Step 1: Install mkcert and Establish a Local Certificate Authority

mkcert is a simple tool for generating locally trusted development certificates. It creates a local Certificate Authority (CA) and then generates certificates signed by this CA. This allows your browser to trust the HTTPS connection to your local server without displaying security warnings.

1. Install mkcert: Open your terminal and use Homebrew to install mkcert:

   brew install mkcert

2. Install the Local Certificate Authority: After installing mkcert, run the following command to install the local CA in your system’s trust store:

   mkcert -install

   This command configures your system to trust certificates issued by mkcert.

3. Generate a Certificate for localhost: To create the necessary certificate and key files for localhost, execute:

   mkcert localhost

   This command will generate two files in your current directory: localhost.pem (the certificate) and localhost-key.pem (the private key). These files will be used by local-ssl-proxy to establish the HTTPS connection.

Step 2: Install and Configure local-ssl-proxy

local-ssl-proxy is a lightweight Node.js proxy that forwards HTTPS requests to your local HTTP server. It uses the certificate and key generated by mkcert to handle the HTTPS connection.

1. Install local-ssl-proxy globally: Use npm to install local-ssl-proxy globally so you can access it from anywhere in your terminal:

   npm install -g local-ssl-proxy

2. Run local-ssl-proxy: Now, start the proxy using the following command, adjusting the ports to match your setup:

   local-ssl-proxy --source 3010 --target 3000 --cert localhost.pem --key localhost-key.pem

   Let’s break down the parameters used in this command:

   • --source 3010: This specifies the port on which the HTTPS proxy will listen. In this case, it’s set to 3010. You can access your application via https://localhost:3010.
   • --target 3000: This is the port where your local HTTP server is running. The proxy will forward all HTTPS requests received on port 3010 to http://localhost:3000. Ensure this port matches the port your development server uses (e.g., for a React, Vue, or Angular application).
   • --cert localhost.pem: This points to the certificate file generated by mkcert (localhost.pem).
   • --key localhost-key.pem: This points to the private key file generated by mkcert (localhost-key.pem).

   [instruction]

[/instruction]

**Alt text:** Terminal displaying commands to install mkcert and local-ssl-proxy using brew and npm on macOS, along with the command to run local-ssl-proxy with specified source and target ports, and certificate/key files for HTTPS proxy setup.

Make sure that the paths to `localhost.pem` and `localhost-key.pem` are correct relative to where you are running the `local-ssl-proxy` command. If you generated them in a different directory, you may need to adjust the paths accordingly.

Step 3: Verify Your HTTPS Setup

1. Start your local HTTP server: Ensure your development application is running on the target HTTP port (e.g., http://localhost:3000). The method to start your server depends on your project (e.g., npm start, yarn serve, python -m http.server, etc.).

2. Access your application via HTTPS: Open your web browser and navigate to https://localhost:3010 (or the port you specified with --source).

   If everything is configured correctly, you should be able to access your local development application over HTTPS without any browser security warnings. The local-ssl-proxy will handle the HTTPS connection and forward requests to your HTTP server running on port 3000.

Conclusion

By following these steps, you have successfully set up an HTTPS proxy for your local HTTP server on macOS. This setup allows you to develop and test your web applications in a secure HTTPS environment, which is increasingly important for modern web development practices and compatibility with various browser features and services. Using mkcert and local-ssl-proxy provides a straightforward and efficient way to achieve this, ensuring a more seamless and production-like local development experience.