# mkcert — Zero-Config Local HTTPS Development Certificates

> mkcert is a simple tool that creates locally-trusted development certificates with zero configuration. No more browser security warnings in local development — just run mkcert and get valid HTTPS for localhost and any custom domain.

## Install

Save as a script file and run:

# mkcert — Zero-Config Local HTTPS Development Certificates

## Quick Use
```bash
# Install mkcert
# macOS
brew install mkcert

# Linux
sudo apt install libnss3-tools
brew install mkcert  # or download binary

# Install the local CA (one-time)
mkcert -install

# Create certificates for localhost
mkcert localhost 127.0.0.1 ::1
# Creates: localhost+2.pem and localhost+2-key.pem

# Create certs for custom domains
mkcert myapp.local "*.myapp.local"
```

## Introduction
mkcert eliminates the pain of HTTPS in local development. Before mkcert, developers either used self-signed certificates (triggering browser warnings), disabled security checks, or went through complex CA setup. mkcert creates a local Certificate Authority, installs it in your system trust store, and generates trusted certificates — all in seconds.

With over 59,000 GitHub stars, mkcert was created by Filippo Valsorda (the same creator of age encryption tool and former Go security lead at Google). It is the standard way to get HTTPS working in local development.

## What mkcert Does
mkcert creates a local Certificate Authority (CA) and installs its root certificate in the system trust store and browsers (Firefox, Chrome, etc.). When you run mkcert with domain names, it generates TLS certificates signed by this local CA. Browsers trust these certificates because they trust the local CA.

## Architecture Overview
```
[mkcert -install]
        |
   [Creates Local CA]
   Root certificate + private key
   stored in mkcert data dir
        |
   [Installs CA in trust stores]
   System keychain (macOS)
   certutil (Linux/Windows)
   Firefox NSS database
        |
[mkcert localhost myapp.local]
        |
   [Generates TLS Certificate]
   Signed by the local CA
   Valid for specified domains
   PEM format output files
        |
   [Use in dev server]
   Node.js, Nginx, Caddy,
   Go, Python, any TLS server
```

## Self-Hosting & Configuration
```bash
# Generate certificates for various scenarios

# Localhost with IP addresses
mkcert localhost 127.0.0.1 ::1

# Custom local domains
mkcert myapp.local api.myapp.local

# Wildcard certificates
mkcert "*.myapp.local" myapp.local

# Use with Node.js
node -e "
const https = require('https');
const fs = require('fs');
const server = https.createServer({
  key: fs.readFileSync('localhost+2-key.pem'),
  cert: fs.readFileSync('localhost+2.pem')
}, (req, res) => res.end('Hello HTTPS!'));
server.listen(3000, () => console.log('https://localhost:3000'));
"

# Use with Nginx
# server {
#   listen 443 ssl;
#   ssl_certificate /path/to/localhost+2.pem;
#   ssl_certificate_key /path/to/localhost+2-key.pem;
# }

# Use with Vite
# vite.config.ts:
# import fs from "fs";
# export default defineConfig({
#   server: {
#     https: {
#       key: fs.readFileSync("localhost+2-key.pem"),
#       cert: fs.readFileSync("localhost+2.pem")
#     }
#   }
# });
```

## Key Features
- **Zero Config** — one command to install CA, one to generate certs
- **System Trust** — certificates are trusted by browsers and OS
- **Multi-Domain** — generate certs for multiple domains at once
- **Wildcard Support** — create wildcard certificates for subdomains
- **Cross-Platform** — works on macOS, Linux, and Windows
- **Firefox Support** — automatically configures Firefox NSS trust store
- **PKCS#12 Export** — generate .p12 files for Java and other platforms
- **No Network** — everything is local, no external CA needed

## Comparison with Similar Tools
| Feature | mkcert | openssl self-signed | Caddy local | step-ca | certbot |
|---|---|---|---|---|---|
| Browser Trusted | Yes | No (warnings) | Via Caddy | Yes | Yes (public) |
| Setup Complexity | 2 commands | Complex | Part of Caddy | Moderate | Moderate |
| Local CA | Yes | Manual | Internal | Yes (full PKI) | No (public CA) |
| Use Case | Dev certs | Manual TLS | Dev server | Internal PKI | Production |
| Wildcard | Yes | Manual | Yes | Yes | Yes |
| Learning Curve | None | High | Low | Moderate | Low |

## FAQ
**Q: Is mkcert secure for production?**
A: No. mkcert is for development only. The local CA private key is stored unencrypted on your machine. For production, use a real CA (via certbot/ACME) or an internal CA (step-ca).

**Q: Does mkcert work with Docker?**
A: Generate certs on your host, then mount them into Docker containers. The container trusts the certs if you also mount and install the root CA inside it.

**Q: How do I use mkcert with custom local domains?**
A: Add entries to /etc/hosts (e.g., "127.0.0.1 myapp.local"), then run "mkcert myapp.local". Your browser will trust HTTPS for that domain.

**Q: Can multiple developers share the same CA?**
A: Each developer should run "mkcert -install" independently. Do not share the CA private key — that would be a security risk.

## Sources
- GitHub: https://github.com/FiloSottile/mkcert
- Created by Filippo Valsorda
- License: BSD-3-Clause

---
Source: https://tokrepo.com/en/workflows/404fae4b-372b-11f1-9bc6-00163e2b0d79
Author: Script Depot