Self-signed development certificates are not trusted by default. mkcert creates a local CA and installs its root in your local trust store, allowing development certificates to validate on configured devices. mkcert is an open-source, cross-platform tool for locally trusted development certificates. The following steps configure it for localhost.
1. Install mkcert
1. Install dependencies where needed
- macOS: if installation reports
x509: certificate signed by unknown authority, you may need Homebrew's ca-certificates package:
brew install curl && brew install openssl && brew install ca-certificates
- Ubuntu: install the required dependencies if they are missing:
sudo apt-get install libnss3-tools
2. Install the tool
- macOS with Homebrew:
brew install mkcert
Windows with Scoop:
scoop install mkcert
Linux: download a binary from the release page or build from source. Move the binary to /usr/local/bin/ and make it executable:
wget "https://github.com/FiloSottile/mkcert/releases/download/v1.4.4/mkcert-v1.4.4-linux-amd64"
sudo mv mkcert-v1.4.4-linux-amd64 /usr/local/bin/mkcert
sudo chmod +x /usr/local/bin/mkcert
2. Generate a certificate
Create a certificate for localhost:
mkcert -install
mkcert localhost 127.0.0.1 ::1
mkcert -install installs the local root CA in supported trust stores so that certificates it signs are trusted locally.
mkcert localhost 127.0.0.1 ::1 creates a certificate covering localhost and the IPv4 and IPv6 loopback addresses.
The output includes a certificate and private key. Use the exact filenames printed by mkcert; the examples below refer to localhost.pem and localhost-key.pem.
3. Use the certificate
1. Node.js with Express
const express = require('express');
const fs = require('fs');
const https = require('https');
const app = express();
const options = {
key: fs.readFileSync('localhost-key.pem'),
cert: fs.readFileSync('localhost.pem'),
};
https.createServer(options, app).listen(3000, () => {
console.log('HTTPS server running on port 3000');
});
2. Nginx
Edit the NGINX site configuration, usually under /etc/nginx/sites-available/default or a similar path:
server {
listen 443 ssl;
server_name localhost;
ssl_certificate /path/to/localhost.pem;
ssl_certificate_key /path/to/localhost-key.pem;
location / {
# Add the application's request handling here.
}
}
Reload NGINX:
sudo service nginx reload
3. Apache
Edit the Apache site configuration, usually under /etc/apache2/sites-available/000-default.conf or a similar path:
<VirtualHost *:443>
ServerName localhost
SSLEngine on
SSLCertificateFile /path/to/localhost.pem
SSLCertificateKeyFile /path/to/localhost-key.pem
# Add the application's request handling here.
</VirtualHost>
Reload Apache:
sudo service apache2 reload
mkcert lets you test realistic HTTPS behavior in local development. Configure each server with the generated files and keep the local CA private key secure.