Configuring SSL certificates in both WSL2 and Windows can be a real headache if you don’t fully understand how these certificates work. The intricacies of certificate authorities, the differences between system and user certificate stores, and the nuances of certificate chains often lead to unexpected problems. Whether you’re dealing with mkcert on Windows or aligning it with your environment in WSL2, understanding these details is key to a secure and trouble-free setup.
Let's walk through the process of installing DDEV in a Windows environment using WSL2 and Docker. The procedure uses Chocolatey to handle the installation of additional tools and runs a script that configures DDEV along with its dependencies.
1. Verify and Adjust the Execution Policy
Before executing scripts downloaded from the Internet, In PowerShell, it is important to check your current execution policy. Run:
The expected output is RemoteSigned (or another configuration defined on your system).
To temporarily allow the execution of scripts in the current session, run:
Note: A message might indicate that the process-level policy is ignored due to a more specific policy. This is normal and only affects the current session.
2. Install Chocolatey
Chocolatey is a package manager for Windows that simplifies the installation of tools. In PowerShell, run:
This command downloads and configures the necessary installation files. It also adds the directory C:\ProgramData\chocolatey\bin to your PATH (if not already present). Once completed, verify the installation by running:
This will display the help and available options for Chocolatey.
3. Install mkcert for SSL Certificates
mkcert is used to easily generate local SSL certificates. In PowerShell, install it using Chocolatey:
Then, run:
This step creates a local Certificate Authority (CA) and installs it into the Windows certificate store so that browsers trust the certificates generated.
4. Configure the CAROOT Environment Variable
To ensure that both Windows and WSL2 recognize the CA created by mkcert, you need to define the CAROOT environment variable. In PowerShell, execute:
This command assigns the CA path (obtained via mkcert -CAROOT) to the CAROOT variable, saves it persistently, and adds it to the WSLENV variable so it propagates into your WSL2 environment.
5. Execute the DDEV WSL2 Docker Inside Installation Script
With Chocolatey and mkcert configured, run the following command in PowerShell to install DDEV and its dependencies (such as gsudo, ngrok, and nssm):
Process Overview:
- Installs or upgrades packages: ddev, gsudo, ngrok, and nssm via Chocolatey.
- Downloads and configures the necessary tools for integrating Windows, WSL2, and Docker.
- Updates required packages in the Ubuntu environment (within WSL2) that are necessary for DDEV.
Warning: During execution, you might see messages related to a "pending system reboot". This is merely a warning and can often be ignored; however, if issues arise, consider restarting your system.
6. Verify the Installation and Configuration of DDEV in WSL2
Once installation is complete, in WSL2, verify that DDEV is installed correctly by running:
The output should display:
- The version of DDEV (e.g., v1.24.4 or higher).
- The architecture (e.g., amd64).
- Information about associated containers, such as the database, web server, router, etc.
- The Docker version installed and its integration with WSL2.
7. Verify certificate location in Windows
Then in PowerShell we have to verify certificate location with next command:
This should return a path similar to:
Where the CA files are located (e.g., the root certificate).
8. Configuring mkcert in WSL2
In order for WSL2 to be able to use the generated CA in Windows, we must configure the CAROOT environment variable.
In WSL2 terminal, assign the variable CAROOT with the path of the Windows CA. Run the following command, replacing your_user with your Windows username:
This way, every time you open WSL2 the CAROOT variable will be set correctly. To confirm if the variable is correctly assigned, we can use the command:
To ensure the value of the variable is correctly assigned, we should see a line in the end of the output of the command like this one:
export CAROOT=/mnt/c/Users/your_user/AppData/Local/mkcert
9. Instalar los certificados en WSL2
With the CAROOT variable set, in the WSL2 terminal run:
This command will take care of registering the root certificate in the WSL2 certificate store (and in the applications that use it).
10. Restart DDEV
For DDEV to apply the new certificate configuration, follow these steps:
Stop all DDEV projects:
Restart the desired project:
During startup, DDEV will configure its containers to use SSL certificates, either automatically generated or those you may have customized in the .ddev/ssl directory.
11. Test HTTPS
Open your browser and access your project URL (e.g. https://your_project.ddev.site).
Verify that the certificate is recognized and does not display security warnings.
Following these steps will allow you to install and configure DDEV with WSL2 and Docker on Windows without major complications. Properly configuring the SSL certificate with mkcert enables you to work securely with HTTPS in your development environment.