How to Set Up Locally Trusted SSL Certificates on Ubuntu with mkcert
Every developer working on a modern web application knows the frustration: you spin up your local server, navigate to localhost, and are immediately greeted by a glaring “Not Secure” warning from your browser. This not only looks unprofessional but can also block access to critical web APIs that require a secure context.
While you can click through the warning, a better solution exists. Setting up a proper HTTPS environment locally ensures your development setup mirrors production, prevents security warning fatigue, and allows you to test features like Service Workers or Geolocation seamlessly.
This guide will walk you through using mkcert, a simple and powerful tool for creating and installing locally-trusted SSL certificates on your Ubuntu system.
Why Local HTTPS is Essential for Modern Development
Before diving into the “how,” let’s quickly cover the “why.” Using HTTPS in your local environment is no longer an optional step; it’s a best practice for several reasons:
- Feature Parity: Many modern browser features and APIs, such as Geolocation, Web Crypto, and Service Workers, are only available in a secure (HTTPS) context. Developing without it means you can’t build or test these features properly.
- Production Mirroring: Your live application runs on HTTPS. Developing locally over HTTP introduces a fundamental difference between your development and production environments, which can lead to unexpected bugs.
- Eliminate Warning Fatigue: Constantly bypassing browser security warnings trains you to ignore them, which is a dangerous habit. A green padlock on your local server reinforces good security practices.
What is mkcert and Why Use It?
Traditionally, creating a local SSL certificate involved complex commands using OpenSSL. The resulting self-signed certificates still triggered browser warnings because they weren’t signed by a trusted Certificate Authority (CA).
mkcert solves this problem elegantly. It’s a zero-configuration command-line tool that:
- Creates its own private Certificate Authority (CA) on your local machine.
- Automatically installs its root certificate into your system and browser trust stores (including Chrome, Firefox, and others).
- Allows you to generate valid, trusted certificates for your local domains (
localhost,myapp.test, etc.) with a single command.
Because your system now trusts the mkcert-generated CA, any certificate signed by it will be fully trusted by your browser, giving you that coveted green padlock.
Step-by-Step Guide to Using mkcert on Ubuntu
Let’s get your local environment secured. This process is straightforward and only needs to be done once per machine.
Step 1: Install Dependencies
mkcert relies on the certutil tool to manage the Firefox trust store. You can install it and its related packages with the following command:
sudo apt update
sudo apt install libnss3-tools
Step 2: Install mkcert
On modern Ubuntu distributions, mkcert is available directly from the default repositories. To install it, simply run:
sudo apt install mkcert
This command will download and install the mkcert tool, making it available system-wide.
Step 3: Create and Install Your Local Certificate Authority (CA)
This is the most critical step. With a single command, you will create your own local CA and install its root certificate into your system’s trust stores.
mkcert -install
You will likely be prompted for your password as this action requires administrative privileges to modify system and browser trust settings. After running this command, you will see a confirmation message indicating where the root CA files have been stored. This is a one-time setup process; you won’t need to run it again unless you reinstall your operating system.
Step 4: Generate a Certificate for Your Local Project
Now you can generate a trusted SSL certificate for any local domain you need. It’s best practice to generate a certificate that is valid for localhost as well as any custom local hostnames you use (like myproject.local).
Navigate to your project’s directory and run the following command:
mkcert myapp.local localhost 127.0.0.1 ::1
This command will create two files in your current directory:
myapp.local+3.pem: The certificate file.myapp.local+3-key.pem: The private key file.
You can now configure your local web server (like Nginx, Apache, or a Node.js server) to use these two files to serve your application over HTTPS.
Important Security Note
It is crucial to understand that certificates generated by mkcert are intended for development purposes only. You should never use them in a production environment.
The private key for the root CA is stored on your local machine, making it fundamentally insecure for anything other than local testing. Always obtain a proper SSL certificate from a public, trusted Certificate Authority like Let’s Encrypt for your live websites.
By following these steps, you can create a seamless and secure local development workflow on Ubuntu, eliminating browser warnings and enabling you to build robust, modern web applications with confidence.
Source: https://kifarunix.com/how-to-create-self-signed-ssl-certificate-with-mkcert-on-ubuntu-18-04/
