Stop Browser Warnings: A Guide to Trusted Local HTTPS with mkcert
If you’re a web developer, you’ve undoubtedly faced the frustrating “Your connection is not private” error in your browser. This warning, often labeled NET::ERR_CERT_AUTHORITY_INVALID, is a common roadblock when trying to run a local development server over HTTPS. While it’s tempting to click “Proceed to unsafe” and ignore it, this workaround is far from ideal. Modern web development often requires a secure context (HTTPS) for features like Service Workers, Geolocation APIs, and secure cookies.
Fortunately, there’s a simple, robust solution that eliminates these warnings for good and creates a local development environment that more accurately mirrors production. Meet mkcert, a zero-config tool for making locally-trusted development certificates.
Why Simple Self-Signed Certificates Aren’t Enough
The traditional approach to local HTTPS involves generating a self-signed SSL certificate. The problem is that browsers have no reason to trust it. A self-signed certificate is like a stranger showing you a homemade ID card—it doesn’t have the backing of a trusted authority. This is why browsers display security warnings, forcing you to manually bypass them on every new browser session or device. This process is not only tedious but also trains you to ignore security warnings, which is a dangerous habit.
How mkcert Solves the Problem
The magic behind mkcert is its ability to create and install its own private Certificate Authority (CA) right on your machine. Think of a CA as a globally recognized entity (like Let’s Encrypt or DigiCert) that vouches for a website’s identity.
Here’s the process mkcert follows:
- It generates a unique, local root Certificate Authority.
- It installs this local CA into your system’s and browser’s trust stores. This is a crucial one-time step.
- Because your system now trusts your local CA, any certificate you generate using
mkcertis automatically trusted by your browser.
The result? No more security warnings, and a seamless, secure local development experience.
A Step-by-Step Guide to Using mkcert on Linux
Getting started with mkcert is incredibly straightforward. Follow these steps to set up a trusted local HTTPS environment on your Linux machine.
Step 1: Install mkcert
The easiest way to install mkcert is through your distribution’s package manager.
For Debian, Ubuntu, and other APT-based systems:
sudo apt update
sudo apt install libnss3-tools
# Download the latest pre-built binary
wget -O mkcert https://github.com/FiloSottile/mkcert/releases/download/v1.4.4/mkcert-v1.4.4-linux-amd64
chmod +x mkcert
sudo mv mkcert /usr/local/bin/
Note: Check the official mkcert GitHub releases page for the latest version.
For Arch Linux:
sudo pacman -S mkcert
If your distribution isn’t listed, you can easily build it from the source if you have Go installed (go install github.com/FiloSottile/mkcert/cmd/mkcert@latest).
Step 2: Create and Install Your Local CA
This is the most important step, but you only need to do it once per machine. Open your terminal and run the following command:
mkcert -install
This command creates the local CA and installs it in the trust stores for major browsers like Chrome and Firefox. You will likely be prompted for your password, as this action requires administrative privileges. You should see a success message confirming the CA was installed.
Step 3: Generate a Certificate for Your Project
Now you can generate a trusted certificate for any local domain you need. Navigate to your project’s directory and run mkcert with the hostnames you use for local development. Common examples include localhost, 127.0.0.1, or a custom domain like my-app.test.
mkcert localhost 127.0.0.1 ::1 my-app.test
This command will create two files in your current directory:
localhost+3.pem: Your certificate file.localhost+3-key.pem: Your private key file.
You can specify as many domains as you need, and mkcert will include all of them in a single certificate.
Step 4: Configure Your Local Server
The final step is to tell your local web server to use the newly generated certificate and key. The exact configuration depends on your development stack.
For a Node.js/Express server, your https setup would look something like this:
const https = require('https');
const fs = require('fs');
const express = require('express');
const app = express();
const options = {
key: fs.readFileSync('./localhost+3-key.pem'),
cert: fs.readFileSync('./localhost+3.pem')
};
app.get('/', (req, res) => {
res.send('Hello, this is a secure server!');
});
https.createServer(options, app).listen(3000, () => {
console.log('Secure server running on https://localhost:3000');
});
Now, when you visit https://localhost:3000 or https://my-app.test:3000 (after adding my-app.test to your /etc/hosts file), you’ll see a green padlock in your browser’s address bar with no security warnings.
Important Security Considerations
While mkcert is a powerful tool for development, it’s essential to use it responsibly.
- For Development Only: The certificates generated by
mkcertare strictly for development purposes. They are not publicly trusted and should never be used on a production server. - Protect Your Root CA Key: The local CA key created by
mkcertis stored in your user’s application data folder. This key is highly sensitive. Never share your root CA private key or check it into a version control system like Git. Anyone with access to it could generate trusted certificates for any domain and potentially intercept your local network traffic. - Uninstalling the CA: If you ever need to remove the local CA from your system, you can do so easily with the command
mkcert -uninstall.
By integrating mkcert into your workflow, you can create a more professional, secure, and efficient local development environment that closely mimics real-world conditions, allowing you to focus on building great applications without fighting your tools.
Source: https://www.tecmint.com/mkcert-create-ssl-certs-for-local-development/
