How to Use mkcert for Local Development SSL

In this tutorial, you'll learn about How to Use mkcert for Local Development SSL. We cover key concepts, practical examples, and best practices.

The Problem

You need HTTPS for local development but self-signed certificates trigger browser security warnings that block mixed content and service workers. Using a real Certificate Authority for localhost is impossible. mkcert creates locally-trusted certificates with zero configuration.

Quick Fix

Step 1: Install mkcert

WRONG — manually creating a CA with OpenSSL:

openssl req -x509 -newkey rsa:4096 -keyout ca-key.pem -out ca-cert.pem -days 3650 -nodes -subj "/CN=LocalDevCA"
# (works but browsers do not trust this CA automatically)

RIGHT — install mkcert and create a local CA:

# On Linux:
sudo apt install libnss3-tools
wget -O mkcert https://github.com/FiloSottile/mkcert/releases/latest/download/mkcert-v1.4.4-linux-amd64
chmod +x mkcert && sudo mv mkcert /usr/local/bin/
mkcert -install
# Created a new local CA at "/home/user/.local/share/mkcert" 💥
# The local CA is now installed in the system trust store! ✅
# The local CA is now installed in the Firefox and/or Chrome trust store! ✅

Step 2: Generate a Local Certificate

mkcert localhost 127.0.0.1 ::1
# Created a new certificate valid for the following names 📜
#  - "localhost"
#  - "127.0.0.1"
#  - "::1"
# Created files:
#   ./localhost+2.pem
#   ./localhost+2-key.pem

Step 3: Use the Certificate

ls -la localhost+2.pem localhost+2-key.pem
# -rw-r--r-- 1 user user 1458 Jun 24 12:00 localhost+2.pem
# -rw------- 1 user user 1704 Jun 24 12:00 localhost+2-key.pem

Serve with a Node.js HTTPS server:

const https = require("https");
const fs = require("fs");
https.createServer({
    key: fs.readFileSync("localhost+2-key.pem"),
    cert: fs.readFileSync("localhost+2.pem"),
}, (req, res) => {
    res.end("Hello HTTPS");
}).listen(443);

Or with Nginx:

server {
    listen 443 ssl;
    server_name localhost;
    ssl_certificate /home/user/projects/localhost+2.pem;
    ssl_certificate_key /home/user/projects/localhost+2-key.pem;
}

Step 4: Verify in Browser

Open https://localhost in your browser. The connection should show a secure lock icon with no warnings.

WRONG — using self-signed certs without adding to trust store:

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/CN=localhost"
# (Chrome shows: NET::ERR_CERT_AUTHORITY_INVALID)

RIGHT — mkcert certificates are trusted because the local CA is installed:

# Open https://localhost
# (shows secure lock icon)

Step 5: Generate for Custom Domains

mkcert myapp.local "*.myapp.local" myapp.test
# Created a new certificate valid for the following names 📜
#  - "myapp.local"
#  - "*.myapp.local"
#  - "myapp.test"

Add the domain to /etc/hosts:

echo "127.0.0.1 myapp.local" | sudo tee -a /etc/hosts

DodaTech's Dev Toolkit includes mkcert integration that auto-generates and refreshes local certificates for all your projects with a single command.

Prevention

• Run mkcert -install once per machine when setting up development.
• Regenerate certificates for new hostnames as needed.
• Keep mkcert up to date with mkcert --version.
• Do not deploy mkcert certificates to production.
• Uninstall the CA with mkcert -uninstall when leaving a project.

Common Mistakes with local dev

1. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable
2. Using head and tail instead of pattern matching, causing runtime errors on empty lists
3. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks

These mistakes appear frequently in real-world MKCERT code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ