From 9fafc6b7e7dfc0c236529be5f34f24a0fe8d642e Mon Sep 17 00:00:00 2001 From: Randy Fay Date: Sat, 15 Nov 2025 09:37:52 -0700 Subject: [PATCH 1/5] Blog update about mkcert and trusted https --- .../ddev-local-trusted-https-certificates.md | 97 ++++++++++++++++--- 1 file changed, 84 insertions(+), 13 deletions(-) diff --git a/src/content/blog/ddev-local-trusted-https-certificates.md b/src/content/blog/ddev-local-trusted-https-certificates.md index 96135413..7e8881de 100644 --- a/src/content/blog/ddev-local-trusted-https-certificates.md +++ b/src/content/blog/ddev-local-trusted-https-certificates.md @@ -1,7 +1,9 @@ --- title: "DDEV Trusted HTTPS Certificates" pubDate: 2019-05-23 -summary: The importance of local HTTPS, and how to take advantage of it with v1.8.0+. +modifiedDate: 2025-11-15 +modifiedComment: Updated to explain Certificate Authorities, how mkcert installs the local CA, and troubleshooting steps for when automatic installation doesn't work. Added reference to detailed browser configuration documentation. +summary: The importance of local HTTPS, and how to take advantage of it with DDEV. author: Randy Fay featureImage: src: /img/blog/2019/05/home-umami.png @@ -11,25 +13,94 @@ categories: - Guides --- -Security is critical on the modern web, and so all sites should ideally be developed, tested, and deployed with HTTPS. But it has been hard to do that in your local development environment. +Security is critical on the modern web, and all sites should ideally be developed, tested, and deployed with HTTPS. But it has been challenging to do that in your local development environment without browser security warnings. -With [DDEV](http://github.com/ddev/ddev) you can use the HTTPS version of your project in a browser that trusts your project and you don’t have to click through the nasty security warning this had triggered previously. +With [DDEV](http://github.com/ddev/ddev) you can use the HTTPS version of your project in a browser that trusts your project, without clicking through security warnings. -HTTPS with DDEV now works… +## TL;DR -- On macOS, Windows, and Linux -- On Firefox, Chrome, Chromium, Safari -- With cURL on the host (macOS and Linux, not Windows) +You don't have to read or understand the rest of this :) There's a one-time installation of trusted HTTPS for DDEV: +``` +mkcert -install && ddev poweroff && ddev start +``` + +## Understanding Certificate Authorities + +When you visit an HTTPS website, your browser verifies the site's SSL/TLS certificate was issued by a trusted **Certificate Authority (CA)**. A CA is an organization that validates website identities and issues digital certificates confirming they are who they claim to be. Your operating system and browsers come with a list of trusted CAs (like Let's Encrypt, DigiCert, or Sectigo). + +For local development, we need a way to create certificates that your system trusts, even though the `.ddev.site` domains aren't publicly accessible. This is where mkcert comes in. + +## How mkcert Works + +[mkcert](https://github.com/FiloSottile/mkcert) is a tool that creates a local Certificate Authority on your computer. When you run `mkcert -install`, it: + +1. Generates a local CA certificate and private key +2. Installs this CA into your system's trust store (macOS Keychain, Windows Certificate Store, or Linux certificate directories) +3. Installs the CA into your browsers' trust stores (Firefox, Chrome, etc.) + +Once this local CA is trusted, mkcert can create SSL certificates for your local domains (like `myproject.ddev.site`), and your browser will trust them automatically because they're signed by your local CA. + +DDEV uses mkcert behind the scenes to generate certificates for each project, so you get automatic HTTPS with no browser warnings. + +## Installation + +HTTPS with DDEV works on: + +- macOS, Windows, and Linux +- Firefox, Chrome, Chromium, Safari, and other browsers +- With cURL on the host (macOS and Linux) - With cURL inside the web container -There is a tiny bit of one-time setup to get your OS and browser to trust the root certificate authority that DDEV uses. The 3-minute screencast below shows how installation and setup works on all 3 platforms. +There is a one-time setup to install the mkcert CA: + +**macOS**: Run `mkcert -install` and provide your password at the sudo prompt. + +**Linux**: Run `mkcert -install` and follow the instructions. You'll likely need to install `libnss3-tools` first: + +```bash +# Debian/Ubuntu +sudo apt-get install -y libnss3-tools + +# Then install the CA +mkcert -install +``` + +**Windows**: Run `mkcert -install` and accept the dialog that pops up. + +## Troubleshooting + +If HTTPS doesn't work after installation, here are common issues: + +### Browsers Still Show Warnings + +Some browsers don't automatically pick up the system trust store. Firefox, in particular, maintains its own certificate store. Run `mkcert -install` which should handle Firefox, but if issues persist, see the [browser configuration documentation](https://docs.ddev.com/en/stable/users/install/configuring-browsers/). + +### cURL Doesn't Trust Certificates + +If you're using a custom-built cURL or one that doesn't respect your system's trust store, you may need to: + +1. Use your system's standard cURL instead +2. Manually configure cURL to trust the mkcert CA +3. Use the `-k` flag (insecure mode) for local development only + +The `curl` inside DDEV's web container is already configured to trust DDEV certificates. + +### Certificate Errors After System Updates + +Occasionally, OS updates can remove trusted CAs. If you start seeing certificate warnings after an update, run `mkcert -install` again to reinstall the local CA. + +### Manual Certificate Installation + +If automatic installation doesn't work, you can manually install the CA certificate. Find it with: -**macOS**: After installing DDEV v1.8.0 and running `ddev stop --all`, run `mkcert -install` and provide your password at the sudo prompt. +```bash +mkcert -CAROOT +``` -**Linux**: After installing DDEV v1.8.0 and `ddev stop --all`, run `mkcert -install` and follow the instructions given. You’ll likely have to install the libnss3-tools package (Debian/Ubuntu `apt-get install -y libnss3-tools`). Add /usr/sbin to your path, and `mkcert -install` again. +Then import the `rootCA.pem` file into your system or browser's certificate store. -**Windows**: After installing DDEV v1.8.0 and `ddev stop --all`, run `mkcert -install` and accept the dialog that pops up. +## More Information -This entire feature is made possible by the outstanding [mkcert](https://github.com/FiloSottile/mkcert) project, another major triumph of open-source and open-source collaboration. Thanks to [@FiloSottile](https://github.com/FiloSottile) for an outstanding project. +For detailed browser configuration and troubleshooting steps, see the [DDEV browser configuration documentation](https://docs.ddev.com/en/stable/users/install/configuring-browsers/). -The [DDEV Installation Documentation](https://docs.ddev.com/en/stable/#installation) has full details about mkcert operation. +This entire feature is made possible by the outstanding [mkcert](https://github.com/FiloSottile/mkcert) project, another triumph of open-source collaboration. Thanks to [@FiloSottile](https://github.com/FiloSottile) for this project. From 1795cdea66d47ba5ad1baba65f6d94856e6fb99e Mon Sep 17 00:00:00 2001 From: Randy Fay Date: Sat, 15 Nov 2025 09:41:54 -0700 Subject: [PATCH 2/5] pacify linters --- src/content/blog/ddev-local-trusted-https-certificates.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/content/blog/ddev-local-trusted-https-certificates.md b/src/content/blog/ddev-local-trusted-https-certificates.md index 7e8881de..985d80af 100644 --- a/src/content/blog/ddev-local-trusted-https-certificates.md +++ b/src/content/blog/ddev-local-trusted-https-certificates.md @@ -20,6 +20,7 @@ With [DDEV](http://github.com/ddev/ddev) you can use the HTTPS version of your p ## TL;DR You don't have to read or understand the rest of this :) There's a one-time installation of trusted HTTPS for DDEV: + ``` mkcert -install && ddev poweroff && ddev start ``` From eaa9085ee28c37a43e7f46ce01efc0804d3826e7 Mon Sep 17 00:00:00 2001 From: Randy Fay Date: Sun, 16 Nov 2025 07:25:42 -0700 Subject: [PATCH 3/5] Minor copilot suggestion Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/content/blog/ddev-local-trusted-https-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/blog/ddev-local-trusted-https-certificates.md b/src/content/blog/ddev-local-trusted-https-certificates.md index 985d80af..54a0e1a5 100644 --- a/src/content/blog/ddev-local-trusted-https-certificates.md +++ b/src/content/blog/ddev-local-trusted-https-certificates.md @@ -27,7 +27,7 @@ mkcert -install && ddev poweroff && ddev start ## Understanding Certificate Authorities -When you visit an HTTPS website, your browser verifies the site's SSL/TLS certificate was issued by a trusted **Certificate Authority (CA)**. A CA is an organization that validates website identities and issues digital certificates confirming they are who they claim to be. Your operating system and browsers come with a list of trusted CAs (like Let's Encrypt, DigiCert, or Sectigo). +When you visit an HTTPS website, your browser verifies that the site's SSL/TLS certificate was issued by a trusted **Certificate Authority (CA)**. A CA is an organization that validates website identities and issues digital certificates confirming they are who they claim to be. Your operating system and browsers come with a list of trusted CAs (like Let's Encrypt, DigiCert, or Sectigo). For local development, we need a way to create certificates that your system trusts, even though the `.ddev.site` domains aren't publicly accessible. This is where mkcert comes in. From 507b9b9f6b65fc8ce59cbeb3d9793c9df6693dcc Mon Sep 17 00:00:00 2001 From: Randy Fay Date: Mon, 17 Nov 2025 07:59:57 -0700 Subject: [PATCH 4/5] more references --- src/content/blog/ddev-local-trusted-https-certificates.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/content/blog/ddev-local-trusted-https-certificates.md b/src/content/blog/ddev-local-trusted-https-certificates.md index 54a0e1a5..f7ec8425 100644 --- a/src/content/blog/ddev-local-trusted-https-certificates.md +++ b/src/content/blog/ddev-local-trusted-https-certificates.md @@ -78,7 +78,7 @@ Some browsers don't automatically pick up the system trust store. Firefox, in pa ### cURL Doesn't Trust Certificates -If you're using a custom-built cURL or one that doesn't respect your system's trust store, you may need to: +If you're using an unusual cURL that doesn't respect your system's trust store, you may need to: 1. Use your system's standard cURL instead 2. Manually configure cURL to trust the mkcert CA @@ -86,6 +86,8 @@ If you're using a custom-built cURL or one that doesn't respect your system's tr The `curl` inside DDEV's web container is already configured to trust DDEV certificates. +(You can figure out which cURL is being used by running `which -a curl`. On Linux you usually want `/usr/bin/curl`, on macOS you might also be using the Homebrew version, `/opt/homebrew/bin/curl`). + ### Certificate Errors After System Updates Occasionally, OS updates can remove trusted CAs. If you start seeing certificate warnings after an update, run `mkcert -install` again to reinstall the local CA. @@ -102,6 +104,8 @@ Then import the `rootCA.pem` file into your system or browser's certificate stor ## More Information -For detailed browser configuration and troubleshooting steps, see the [DDEV browser configuration documentation](https://docs.ddev.com/en/stable/users/install/configuring-browsers/). +* For detailed browser configuration and troubleshooting steps, see the [DDEV browser configuration documentation](https://docs.ddev.com/en/stable/users/install/configuring-browsers/). +* Read more about how all of this works in [Hostnames and Wildcards and DDEV, Oh My!](ddev-name-resolution-wildcards). +* The [mkcert project](https://github.com/FiloSottile/mkcert) has more information and documentation. This entire feature is made possible by the outstanding [mkcert](https://github.com/FiloSottile/mkcert) project, another triumph of open-source collaboration. Thanks to [@FiloSottile](https://github.com/FiloSottile) for this project. From 1166529c735850e3cce769c482323254e2252047 Mon Sep 17 00:00:00 2001 From: Randy Fay Date: Mon, 17 Nov 2025 11:47:50 -0700 Subject: [PATCH 5/5] @stasadev suggestion, thanks! Co-authored-by: Stanislav Zhuk --- src/content/blog/ddev-local-trusted-https-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/blog/ddev-local-trusted-https-certificates.md b/src/content/blog/ddev-local-trusted-https-certificates.md index f7ec8425..d4124337 100644 --- a/src/content/blog/ddev-local-trusted-https-certificates.md +++ b/src/content/blog/ddev-local-trusted-https-certificates.md @@ -105,7 +105,7 @@ Then import the `rootCA.pem` file into your system or browser's certificate stor ## More Information * For detailed browser configuration and troubleshooting steps, see the [DDEV browser configuration documentation](https://docs.ddev.com/en/stable/users/install/configuring-browsers/). -* Read more about how all of this works in [Hostnames and Wildcards and DDEV, Oh My!](ddev-name-resolution-wildcards). +* Read more about how all of this works in [Hostnames and Wildcards and DDEV, Oh My!](ddev-name-resolution-wildcards.md). * The [mkcert project](https://github.com/FiloSottile/mkcert) has more information and documentation. This entire feature is made possible by the outstanding [mkcert](https://github.com/FiloSottile/mkcert) project, another triumph of open-source collaboration. Thanks to [@FiloSottile](https://github.com/FiloSottile) for this project.