How to Use 'mkcert' Command (with examples)

mkcert is a simple tool for making locally-trusted development certificates. It is a convenient utility for developers who work with HTTPS during development. mkcert bypasses the need for obtaining certificates from a Certificate Authority (CA) by allowing you to generate certificates that are trusted by browsers on your machine. This helps create a secure environment for testing applications with HTTPS locally.

Install the local CA in the system trust store

Code:

mkcert -install

Motivation:

When dealing with development projects, using HTTPS is essential for replicating production environments accurately. However, browsers are often skeptical about self-signed certificates, leading to security warnings. By installing a local Certificate Authority (CA) in the system’s trust store, mkcert creates certificates that are recognized as valid by the browser, eliminating these warnings and ensuring a smoother development experience.

Explanation:

• -install: This argument tells mkcert to install a local Certificate Authority (CA) in your system’s trust store, allowing it to sign certificates for use in local development. This process adjusts your system settings to recognize and trust certificates generated by mkcert.

Example Output:

Created a new local CA at "/Users/username/Library/Application Support/mkcert" 💥
The local CA is now installed in the system trust store! ⚡️

Generate certificate and private key for a given domain

Code:

mkcert example.org

Motivation:

While developing applications that require HTTPS, it is important to have valid certificates for the domains you are working with, even in a local environment. This use case allows developers to generate a certificate and a corresponding private key for a specific domain, facilitating secure connections specific to the domain of interest.

Explanation:

• example.org: This is the domain for which you want to generate the certificate and private key. The domain can be any hostname you require for your project, such as a local hostname.

Example Output:

Created a new certificate valid for the following names 📜
 – "example.org"

The certificate is at "./example.org.pem" and the key at "./example.org-key.pem" ✅

Generate certificate and private key for multiple domains

Code:

mkcert example.org myapp.dev 127.0.0.1

Motivation:

Devs often work with multiple hostnames during development, such as different environments or different apps communicating with each other. This functionality allows you to generate a single certificate valid for several domains. It includes IP addresses, making it a versatile and time-saving option, particularly for microservices or systems involving numerous local services.

Explanation:

• example.org, myapp.dev, 127.0.0.1: These are the hostnames and IP addresses for which the certificate is being issued. By providing multiple, the command generates a certificate that is valid across all specified domains and IPs.

Example Output:

Created a new certificate valid for the following names 📜
 – "example.org"
 – "myapp.dev"
 – "127.0.0.1"

The certificate is at "./example.org+2.pem" and the key at "./example.org+2-key.pem" ✅

Generate wildcard certificate and private key for a given domain and its subdomains

Code:

mkcert "*.example.it"

Motivation:

In scenarios where you have various subdomains under a main domain for your application (e.g., blog.example.it, shop.example.it), a wildcard certificate proves beneficial. It ensures all subdomains are covered under a single certificate, hence avoiding the need for generating separate certificates for each subdomain, simplifying the management in development setups with numerous subdomains.

Explanation:

• "*.example.it": The wildcard character * allows the certificate to be valid for any subdomain of example.it. This includes multiple subdomains without the need to generate and validate individual certificates for each one.

Example Output:

Created a new certificate valid for the following names 📜
 – "*.example.it"

The certificate is at "./_wildcard.example.it.pem" and the key at "./_wildcard.example.it-key.pem" ✅

Uninstall the local CA

Code:

mkcert -uninstall

Motivation:

At times, you might want to remove the root Certificate Authority installed by mkcert from your system, either because you no longer need it, or you’re transitioning to a production environment and want to clear development settings. The uninstall feature cleanly removes the CA, ensuring no unnecessary settings linger in your system trust store that might affect other operations.

Explanation:

• -uninstall: This argument instructs mkcert to remove the local CA from the system’s trust store, essentially undoing the -install command and removing the system’s trust in any certificates generated by this CA.

Example Output:

The local CA is now uninstalled from the system trust store(s)! 🗑️

Conclusion

mkcert provides developers with an efficient way to create locally-trusted certificates, significantly enhancing the development experience by simulating real-world HTTPS environments. Whether you need a certificate for a single domain, multiple domains, or wildcard subdomains, mkcert offers user-friendly solutions. Additionally, the ability to cleanly install and uninstall local CAs ensures that developers can manage their environment settings with ease.