Creating Locally Trusted SSL Certificates using mkcert

Josphat Mutai
May 19, 2025
10:37 pm
No Comments

Are you tired of dealing with untrusted SSL certificates in your local development projects? Managing your own Certificate Authority (CA) can be a real headache – full of outdated procedures and cryptic commands. In this guide, I’ll show you a simple and effective way to use trusted SSL certificates on your local development machine, without the hassle of running your own CA.

mkcert is a simple, zero-configuration tool written in Go by Filippo Valsorda. It allows you to generate locally trusted development certificates for any domain name without needing to configure anything manually. This is especially useful because trusted Certificate Authorities (CAs) won’t issue certificates for local domains that lack valid DNS records. In this guide, we’ll walk through how to install and use mkcert to simplify your local HTTPS development.

Install mkcert on Ubuntu / Debian

To install mkcert on any Ubuntu or Debian system, first, install certutil dependencies:

sudo apt update
sudo apt install wget libnss3-tools

Once this has been installed, download mkcert binary package from Github. Check mkcert releases page for the latest version.

curl -s https://api.github.com/repos/FiloSottile/mkcert/releases/latest| grep browser_download_url  | grep linux-amd64 | cut -d '"' -f 4 | wget -qi -

Once the file has been downloaded, make the file executable and place the binary under /usr/loa/bin

mv mkcert-v*-linux-amd64 mkcert
chmod a+x mkcert
sudo mv mkcert /usr/local/bin/

Install mkcert on RHEL-based systems

Installation of mkcert on RHEL-based Linux systems is similar to Ubuntu/Debian installation. You only need to install nss-tools tools first.

sudo yum install nss-tools

Once installed, download the binary package like for Ubuntu installation.

curl -s https://api.github.com/repos/FiloSottile/mkcert/releases/latest| grep browser_download_url  | grep linux-amd64 | cut -d '"' -f 4 | wget -qi -

Once the file has been downloaded, make the file executable and place the binary under /usr/local/bin

mv mkcert-v*-linux-amd64 mkcert
chmod a+x mkcert
sudo mv mkcert /usr/local/bin/

Confirm it works:

$ mkcert --version
v1.4.4

Install mkcert on Arch Linux | Manjaro | Garuda

For Arch Linux, you can install mkcert using the above procedure or using AUR. For installation, you need to use an AUR helper, I recommend yay for this:

yay – Best AUR Helper for Arch Linux / Manjaro

Once you install yay, install mkcert from it using:

yay -S --noconfirm --needed go
yay -S --noconfirm --needed mkcert

How to Install mkcert on macOS

For macOS users, you can download the binary package or install mkcert from.brew

brew install mkcert
brew install nss # if you use Firefox

For binary install:

curl -s https://api.github.com/repos/FiloSottile/mkcert/releases/latest| grep browser_download_url  | grep darwin-amd64 | cut -d '"' -f 4 | wget -qi -

Once the file has been downloaded, make the file executable and place the binary under /usr/local/bin

mv mkcert-v*-darwin-amd64 mkcert
chmod a+x mkcert
sudo mv mkcert /usr/local/bin/

Confirm successful installation by checking the version:

$ mkcert --version
v1.4.4

Install mkcert on Windows

If you are using Windows OS, you can use Chocolatey

choco install mkcert

or use Scoop

scoop bucket add extras
scoop install mkcert

Use mkcert to generate locally trusted SSL certificates

mkcert has support for the following root stores:

macOS system store
Windows system store
Linux variants that provide either
- update-ca-trust (Fedora, RHEL, CentOS) or
- update-ca-certificates (Ubuntu, Debian)
Firefox (macOS and Linux only)
Chrome and Chromium
Java (when JAVA_HOME is set)

To get the help page for mkcert, pass the option--help.

Usage of mkcert:

	$ mkcert -install
	Install the local CA in the system trust store.

	$ mkcert example.org
	Generate "example.org.pem" and "example.org-key.pem".

	$ mkcert example.com myapp.dev localhost 127.0.0.1 ::1
	Generate "example.com+4.pem" and "example.com+4-key.pem".

	$ mkcert "*.example.it"
	Generate "_wildcard.example.it.pem" and "_wildcard.example.it-key.pem".

	$ mkcert -uninstall
	Uninstall the local CA (but do not delete it).

Advanced options:

	-cert-file FILE, -key-file FILE, -p12-file FILE
	    Customize the output paths.

	-client
	    Generate a certificate for client authentication.

	-ecdsa
	    Generate a certificate with an ECDSA key.

	-pkcs12
	    Generate a ".p12" PKCS #12 file, also know as a ".pfx" file,
	    containing certificate and key for legacy applications.

	-csr CSR
	    Generate a certificate based on the supplied CSR. Conflicts with
	    all other flags and arguments except -install and -cert-file.

	-CAROOT
	    Print the CA certificate and key storage location.

	$CAROOT (environment variable)
	    Set the CA certificate and key storage location. (This allows
	    maintaining multiple local CAs in parallel.)

	$TRUST_STORES (environment variable)
	    A comma-separated list of trust stores to install the local
	    root CA into. Options are: "system", "java" and "nss" (includes
	    Firefox). Autodetected by default.

You can get your CA root directory using:

$ mkcert -CAROOT
/root/.local/share/mkcert

You need to start by installing the local CA in your system trust store.

# mkcert -install
The local CA is now installed in the system trust store! ⚡️
The local CA is now installed in the Firefox and/or Chrome/Chromium trust store (requires browser restart)! 🦊

Once done, you can start generating SSL certificates for your domains. As an example, I’ll generate a new certificate valid for the following names:

- "mydomain.com"
- "*.mydomain.co"
- "myapp.net"
- "localhost"
- "127.0.0.1"
- "::1"

The output will be like below:

# mkcert mydomain.com '*.mydomain.co' myapp.net localhost 127.0.0.1 ::1
Created a new certificate valid for the following names 📜
 - "mydomain.com"
 - "*.mydomain.co"
 - "myapp.net"
 - "localhost"
 - "127.0.0.1"
 - "::1"

Reminder: X.509 wildcards only go one level deep, so this won't match a.b.mydomain.co ℹ️

The certificate is at "./mydomain.com+5.pem" and the key at "./mydomain.com+5-key.pem" ✅

It will expire on 11 January 2024 🗓

You should be able to view the contents of the certificate:

# cat ./mydomain.com+5.pem
-----BEGIN CERTIFICATE----- MIIEVDCCArygAwIBAgIRAL2vyvexRiXjWMWF688t9RswDQYJKoZIhvcNAQELBQAw WTEeMBwGA1UEChMVbWtjZXJ0IGRldmVsb3BtZW50IENBMRcwFQYDVQQLDA5yb290 QHVidW50dS0wMTEeMBwGA1UEAwwVbWtjZXJ0IHJvb3RAdWJ1bnR1LTAxMB4XDTE4 MDgxNTA2MjIzMFoXDTI4MDgxNTA2MjIzMFowQjEnMCUGA1UEChMebWtjZXJ0IGRl dmVsb3BtZW50IGNlcnRpZmljYXRlMRcwFQYDVQQLDA5yb290QHVidW50dS0wMTCC ASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMg6ByQe5vjX65HYoOe/QyRo yotQOvBX8k8RJxQSXmTYsTGeYjTtlfLlubJ/AmGovzfPK6CmSWkTK6czENsR2DBH mAHyyu1PdeJihnBZSNAlkEIGNPZvxqKlNZvqe1gxMntHG569YKBl52EaiMiDu3D0 yk+dvIHuCtvGseFUxRwnc4gq4B6yhyGR6y1dmL7eZkrIAgMHxdktavThscvJ3N7A N4dY7iackLiajqjRzT6/iVR0NRRbqxDlgsfrq6MGkAnri56LuZBZmyF85c+kpvuN bHEAAUvxziHORX0+NmBedcajr16rYV4+/IJXbY2llLkprRG2Ar8CqrblH2uBX+8C AwEAAaOBrTCBqjAOBgNVHQ8BAf8EBAMCBaAwEwYDVR0lBAwwCgYIKwYBBQUHAwEw DAYDVR0TAQH/BAIwADAfBgNVHSMEGDAWgBRLV1qAcMY0/atqn4AS3sWCOoo4OTBU BgNVHREETTBLggxteWRvbWFpbi5jb22CDSoubXlkb21haW4uY2+CCW15YXBwLm5l dIIJbG9jYWxob3N0hwR/AAABhxAAAAAAAAAAAAAAAAAAAAABMA0GCSqGSIb3DQEB CwUAA4IBgQBaQcM7oe4TNQfdwvkZk0rTK1aoXteBF7JqxdhFqL1wWNAO+HTsRuzO My19o3mL+9SVjuv1NCEUCVGXQ5FK+HFdBdWm1cAKzHM/j6pwo0k60K9kIfyQZfsh GjDDtrE+86T16JwWTozFyyZHDAhskQuudwha4pZWgrwZudAdqaAOQW59+8s3gYaj Wd10hiptLbAnhd3DKPgnhjgpIT6zvtJ7gvm8fXVwOyoPfbIm3kl94rIa0BVrhmeA ma227ehRK0iUwA1oclZ4dbRfcjNgL79ryVgffOgTD1O3mWzwvGenD7/oG9FZQ2fK WPdh4gdV+f5fZ+GiLA2KPIShrReFlt70pUJDkDHT0AEuSiFZQ5vVc3KV/3k3HUTJ tmkiePMoMGB/kEVyo1is3NDUBkofMTYSFjVdSgZ9rrefoUe/tfqBeh5IV+ZRUv3p kSsXe0sBnqtSa5ExQ+Uv2X6/jEBBEAoYN6GmL+poV06Ra6/nnXPnaRLkQ/8CT8sp xKtvdnyDa6Y= -----END CERTIFICATE-----

The private key is:

ls mydomain.com+5-key.pem

Testing mkcert certificate

Let’s now test mkcert certificate using a simple Nginx configuration file. Forgive me this example is done on Ubuntu 18.04 system.

### Ubuntu / Debian ###
sudo apt update
sudo apt install nginx

### CentOS / Fedora ###
sudo yum install nginx
sudo systemctl enable --now nginx

Create a simple web page

# vim /etc/nginx/conf.d/test.conf 
server {
   listen 80;
   server_name mydomain.com myapp.net;
   root /var/www/test;
}

server {
   listen *:443 ssl http2;
   root /var/www/test;
   server_name mydomain.com myapp.net;
   ssl_certificate /root/mydomain.com+5.pem; 
   ssl_certificate_key /root/mydomain.com+5-key.pem;
}

Make sure your /etc/hosts file has a record for used domains.

127.0.0.1 myapp.net
127.0.0.1 mydomain.com

Open your browser and use domain provided, you should get a green bar.

Join our Linux and open source community. Subscribe to our newsletter for tips, tricks, and collaboration opportunities!

Unlock the Right Solutions with Confidence

At CloudSpinx, we don’t just offer services - we deliver clarity, direction, and results. Whether you're navigating cloud adoption, scaling infrastructure, or solving DevOps challenges, our seasoned experts help you make smart, strategic decisions with total confidence. Let us turn complexity into opportunity and bring your vision to life.

Elearning

Cloud Services

Infra Services

Iac & GitOps

IT Support

InfoSec

Development