Understanding mkcert

mkcert is a simple utility designed for creating locally trusted SSL/TLS development certificates. It eliminates the complexity typically associated with generating certificates, requiring absolutely no configuration. The tool automatically manages a local Certificate Authority (CA) that is trusted by your operating system and browser. This utility is cross-platform, fully supporting Windows, macOS, and Linux environments.

Repository:
https://github.com/FiloSottile/mkcert

Installation Guide

On macOS

brew install mkcert
brew install nss # Only required if using Firefox

On Linux

# Install dependencies
sudo apt install libnss3-tools
# Or
sudo yum install nss-tools

# Download the latest binary
curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
chmod +x mkcert-v*-linux-amd64
sudo cp mkcert-v*-linux-amd64 /usr/local/bin/mkcert

On Windows

choco install mkcert
# Or using Scoop
scoop bucket add extras
scoop install mkcert

Implementation Guide

To demonstrate the functionality, we will set up a secure local web server accessible via app.local. This involves generating certificates, configurnig Nginx, and running the setup in a Docker container.

1. Project Setup

Create a directory structure to hold the configuration, web content, and encryption keys.

mkdir -p ~/local-ssl-demo/{html,keys,config}

2. Certificate Generation

Navigate to the keys directory and generate the certificate for the desired domain.

cd ~/local-ssl-demo/keys
mkcert app.local localhost

Upon execution, the tool outputs the location of the generated files:

The certificate is at "./app.local+1.pem" and the key at "./app.local+1-key.pem" ✅

3. Web Content

Create a basic HTML file to serve as the landing page.

vim ~/local-ssl-demo/html/index.html

index.html content:

<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Secure Dev Environment</title>
    <style>
        body { font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; background-color: #eef2f5; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; }
        .container { background: white; padding: 40px; border-radius: 8px; box-shadow: 0 4px 6px rgba(0,0,0,0.1); text-align: center; }
        h1 { color: #2c3e50; }
    </style>
</head>
<body>
    <div class="container">
        <h1>Connection Secure</h1>
        <p>Successfully accessing app.local via HTTPS.</p>
    </div>
</body>
</html>

4. Web Server Configuration

Configure Nginx to handle HTTPS traffic using the newly created certificates.

vim ~/local-ssl-demo/config/nginx.conf

nginx.conf content:

worker_processes 1;

events {
    worker_connections 1024;
}

http {
    server {
        listen 443 ssl;
        server_name app.local;

        ssl_certificate /etc/nginx/ssl/app.local+1.pem;
        ssl_certificate_key /etc/nginx/ssl/app.local+1-key.pem;

        location / {
            root /usr/share/nginx/html;
            index index.html;
        }
    }
}

5. Deployment

Launch the Nginx container using Docker, mounting the necessary volumes.

docker run -d \
  --name local-ssl-server \
  -p 8443:443 \
  -v ~/local-ssl-demo/config/nginx.conf:/etc/nginx/nginx.conf:ro \
  -v ~/local-ssl-demo/html:/usr/share/nginx/html:ro \
  -v ~/local-ssl-demo/keys:/etc/nginx/ssl:ro \
  nginx:alpine

6. Trusting the Certificate Authority

When you first access the site (e.g., at https://localhost:8443), the browser may flag the connection as insecure. This happens if the local CA is not yet recognized by the client system. To resolve this, install the local CA.

On the host machine running the browser, execute:

mkcert -install

If the CA needs to be installed on a different machine (like a mobile device or separate PC), locate the CA files using:

mkcert -CAROOT

This command prints the path containing rootCA.pem and rootCA-key.pem. Copy rootCA.pem to the target device.

Manual Installation (Windows):
Rename rootCA.pem to rootCA.crt. Double-click the file, select Install Certificate, and place it in the Trusted Root Certification Authorities store.

After completing these steps, refresh the browser. The connection should now be reported as secure.

Summary

mkcert provides an efficient workflow for setting up HTTPS in local development environments. By handling the creation and trust of a local Certificate Authority automatically, it significantly reduces the friction compared to using OpenSSL or other manual methods. Its an essential tool for developers working on APIs, microservices, or web applications that require SSL validation locally before production deployment.