Skip to main content
Certificate issuance

Create Trusted Localhost Certificates with mkcert

Use the open-source mkcert tool to create locally trusted certificates for development.

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.