What it is
mkcert is a utility for generating locally trusted TLS certificates for development environments.
Installation
Linux
sudo apt update && sudo apt install libnss3-tools
mkcert -install
or
sudo yum install nss-tools
mkcert -install
macOS
brew install nss
mkcert -install
Windows
Download the executable from the mkcert releases page.
# Assuming mkcert.exe is in your PATH or current directory
mkcert -install
To add mkcert to your PATH, you can download the binary and place it in a directory that is already in your system’s PATH environment variable.
Core Concepts
Certificate Authority (CA)
mkcert creates its own local Certificate Authority (CA) and installs it into your operating system’s trust store. This means browsers and other applications that trust your OS’s CA store will automatically trust certificates signed by your mkcert CA.
Certificates
When you request a certificate for a domain (e.g., localhost), mkcert uses its local CA to sign that certificate. This allows you to use HTTPS in your local development environment without encountering browser warnings.
Commands / Usage
Installing the Local CA
This command creates a new local CA and installs it into the trust stores of various applications (browsers, Docker, etc.). You’ll need to run this once per machine.
mkcert -install
Explanation: Installs the mkcert local Certificate Authority into the system’s trust store.
Generating Certificates
Generates a certificate and private key for the specified hostnames.
mkcert example.com localhost 127.0.0.1 ::1
Explanation: Creates example.com.pem (certificate) and example.com.key (private key) files for example.com, localhost, 127.0.0.1, and ::1.
mkcert myapp.local
Explanation: Creates myapp.local.pem and myapp.local.key for the hostname myapp.local.
Generating Certificates with an Organization Name
You can specify an organization name that will be embedded in the certificate’s subject.
mkcert -org "My Dev Company" api.internal.dev
Explanation: Generates certificates for api.internal.dev with the organization set to "My Dev Company".
Generating Certificates with Custom Output Directory
Specify a directory where the certificate and key files should be saved.
mkcert -CARO /path/to/certs/ myapp.local
Explanation: Creates certificate and key files for myapp.local in /path/to/certs/ and also saves the CA certificate there.
Listing Installed CAs
Shows the paths to the CA certificates that mkcert has installed.
mkcert -CARO
Explanation: Lists the paths of the CA certificates installed by mkcert.
Uninstalling the Local CA
Removes the mkcert local Certificate Authority from the system’s trust store.
mkcert -uninstall
Explanation: Uninstalls the mkcert local Certificate Authority.
Cleaning Up Expired Certificates
Removes certificates that have expired from mkcert’s internal cache.
mkcert -clean
Explanation: Removes expired certificates and keys from mkcert’s internal storage.
Inspecting Certificates
Prints information about a certificate file.
mkcert -inspect example.com.pem
Explanation: Displays details about the example.com.pem certificate.
Overriding the CA Directory
By default, mkcert stores its CA in ~/.local/share/mkcert. You can override this.
# Set environment variable before running mkcert commands
export MKCERT_HOME=/path/to/custom/mkcert/data
mkcert -install
mkcert myapp.local
Explanation: Configures mkcert to use /path/to/custom/mkcert/data for its CA and certificate storage.
Common Patterns
Serving a Local Development Server with HTTPS
Assuming you have a Node.js server:
# Generate certificates
mkcert myapp.local
# Start your Node.js server using the generated certs
node server.js
And in server.js:
const https = require('https');
const fs = require('fs');
const express = require('express');
const app = express();
const options = {
key: fs.readFileSync('myapp.local-key.pem'),
cert: fs.readFileSync('myapp.local.pem')
};
app.get('/', (req, res) => {
res.send('Hello from HTTPS!');
});
https.createServer(options, app).listen(3000, () => {
console.log('Server listening on https://myapp.local:3000');
});
Configuring Docker Compose for HTTPS
If your services need to communicate over HTTPS locally:
# docker-compose.yml
version: '3.8'
services:
backend:
image: my-backend-app
ports:
- "443:443"
volumes:
- ./certs:/etc/ssl/certs # Mount your mkcert generated certs
# ... other configurations
# Run mkcert to generate certificates
mkcert myapp.backend.local
# Build and run your services
docker-compose up -d
Your backend application would then be configured to use the certificates from /etc/ssl/certs.
Generating Certificates for Multiple Domains and IP Addresses
Combine various host identifiers.
mkcert -install
mkcert api.dev localhost 192.168.1.100 10.0.0.5
Explanation: Creates certificates for the domain api.dev, the hostname localhost, and the IP addresses 192.168.1.100 and 10.0.0.5.
Gotchas
Browser Caching
Sometimes, even after regenerating certificates or reinstalling the CA, browsers might still show old certificate warnings. Clearing your browser’s cache or restarting the browser can resolve this.
Operating System Trust Store Updates
On some systems, especially after OS updates, the trust store might be reset or require re-authentication. You might need to run mkcert -install again.
Application-Specific Trust Stores
While mkcert -install tries to cover common applications, some tools (e.g., certain command-line clients, older Java applications) might have their own trust stores that need to be manually configured to trust the mkcert CA. You can find the mkcert CA certificate at the path shown by mkcert -CARO.
Permissions for CA Installation
On Linux and macOS, mkcert -install usually requires sudo or administrator privileges to write to system-wide trust stores. If it fails, check your permissions.
Certificate Expiration
mkcert certificates are valid for a long time by default (e.g., 10 years). However, if you need to renew them or if you’ve changed the CA, you might need to generate new certificates and update your application configurations. mkcert -clean helps manage expired ones.