DDEV Test Environment for OpenMage in Windows 10/11

[addison74]

Last update February 27, 2025

VMware Workstation - Free for Personal Use

In this tutorial I used VMware Workstation as a desktop hypervisor. Starting with spring 2024, the new owner Broadcom has decided to provide the application with two license models, Free Personal Use or Paid Commercial use. So, you can use this application for free as long as it is for personal use. I encourage everyone to use VMware because compared to its competitors (VirtualBox, Microsoft Hyper-V) it has better performance especially on the graphics side. A Windows 10 or 11 operating system runs in a virtual machine pretty decent to a real one.

For more details read this article
https://blogs.vmware.com/workstation/2024/05/vmware-workstation-pro-now-available-free-for-personal-use.html

VMware Workstation Settings

If you run Windows OS in a virtual machine, it is mandatory to activate the virtualization option. For example, in VMware with the virtual machine off, access Edit virtual machine settings. In the Hardware tab select Processors and in the Virtualization engine section check the Virtualize Intel VT-x/EPT or AMD-V/RVI option.

You need at least 8 GB of memory to run (Docker + PHPStorm) decent. I recommend a machine with 16 GB.

(Windows) Installing the Windows Terminal Application

1. Open the Microsoft Store application and search for Windows Terminal
2. Choose the first result then press the Get button

If you use PHPStorm, at the bottom there is a tab called Terminal. Here you can run commands in the Linux distribution too.

(Windows) Installing WSL2 (Windows Subsystem for Linux 2)

The Installation Tutorial
https://pureinfotech.com/install-windows-subsystem-linux-2-windows-10/

Useful Commands
https://learn.microsoft.com/en-us/windows/wsl/

wsl --install
wsl --version
wsl --update
wsl --list --online
wsl --install -d DISTRO-NAME
wsl --set-version <distro name> 2

Advanced Settings
https://learn.microsoft.com/en-us/windows/wsl/wsl-config#configure-global-options-with-wslconfig

You can configure limits on the memory, CPU and swap size allocated to WSL 2 in a .wslconfig file⁠. For example, create a file named .wslconfig in the C:\Users\<User Name> directory with the following content

[wsl2]
memory=4GB   # Limits VM memory in WSL 2 up to 4 GB
processors=6 

(Windows) Installing a Linux Distribution

Variant 1

1. Open the Command Prompt application as Administrator
2. Get the distributions list wsl --list --online
3. Install a distribution wsl --install -d Ubuntu-20.04
4. Reboot the system

Variant 2

1. Open the Microsoft Store application and search for Ubuntu
2. Install an LTS version, for example Ubuntu 20.04.6 LTS
3. Reboot the system

Open the Terminal application then choose a new tab with Ubuntu. Follow the steps to complete the installation, setting the username and password (e.g. ubuntu / 1234).

(Windows) Installing Docker

https://docs.docker.com/desktop/install/windows-install/

1. Download the installation file Docker Desktop Installer.exe and run it as Administrator
2. During installation check the option Use WSL 2 instead of Hyper-V (recommended)
3. Reboot the system

(Windows) Installing mkcert for Secured Connections

https://github.com/FiloSottile/mkcert

1. Download the latest Windows release
2. Open the Terminal application as Administrator
3. Go to the directory where you downloaded the executable file named mkcert-vX.X.X-windows-amd64.exe
4. Run mkcert-vX.X.X-windows-amd64.exe --install
5. In the popup window, where you are asked if you want to install the certificate, press Yes

(Windows) Linux distribution drive mapping

1. Open the Windows Explorer application
2. On the left side open the Linux path and select Ubuntu-20.04
3. Right-click and select Map network drive... from the menu. Choose a letter, for example Z:

From now on it appears in the This PC section under Network locations. If you want to disconnect it, right-click and select Disconnect from the menu.

(Windows) PHPStorm

Create a new project in PHPStorm that has the location where you cloned the OpenMage repository. If you log in to your GitHub account, you will see in the Pull Request tab on the left the open PRs from OpenMage. Open one and checkout to start testing. When you are done, at the bottom of the PHPStorm window you will see the Git tab. Click on it, then right click on Local > main and select Checkout. You can update the repositories, locals and remotes, from time to time and more.

(Linux) Installing DDEV

https://ddev.readthedocs.io/en/latest/users/install/ddev-installation/

1. Open the Terminal application and choose a new tab with Ubuntu
2. Bring all the packages up to date Ubuntu sudo apt update && sudo apt upgrade -y
3. Install DDEV according to the instructions

(Linux) Copying mkcert Certificates from Windows to Linux

Variant 1

1. Open the Terminal application and choose a new tab with Ubuntu
2. Create the path mkdir -p /home/<user_name/.local/share/mkcert
3. Run cp /mnt/c/Users/<User Name>/AppData/Local/mkcert/* /home/<user_name>/.local//share/mkcert/

Variant 2

1. Run the Windows Explorer application as administrator
2. Copy the files rootCA.pem and rootCA-key.pem from C:\Users\<User Name>\AppData\Local\mkcert
3. Create the path in Linux > Ubuntu-20.04 /home/<user_name/.local/share/mkcert
4. Paste them in the mkcert directory

(Linux) Installing OpenMage

First make sure that the Docker Desktop application is running in Windows.

1. Open the Terminal application and choose a new tab with Ubuntu
2. Create the path mkdir -p /home/<user_name>/openmage
3. Clone the OpenMage repository git clone https://github.com/OpenMage/magento-lts.git /home/<user_name>/openmage
4. Go to the directory /home/<user_name>/openmage
5. Run the following DDEV commands. The first command configures the project, the second installs OpenMage dependencies, the third installs Magento Sample Data.

ddev config
ddev composer install
ddev openmage-install -s -k

6. Edit the .ddev/config.yaml file to change the webserver and PHP version as you want. I am using Apache and PHP 8.3

php_version: "8.3"
webserver_type: apache-fpm

7. Run the following DDEV commands to load the project in the browser window with a secured connection

ddev start
ddev launch

(WSL) The xdg-open error when running the ddev launch command

If you encounter errors when running the ddev launch command, related to xdg-open and a long list of missing Linux browsers it is normal. DDEV wants to launch an installed browser in WSL and since there is none, we have to configure to use the default one in Windows. All you have to do is editing the ~/.bashrc file and adding the following line to the end

export BROWSER="powershell.exe /C start"

For the change to take effect, run . .bashrc..

Another variant would be to install in WSL the wslu package.

Conclusion

As you can see, the more complicated part is the initial configuration of WSL, Docker, DDEV. Once done, it doesn't take more than 3-5 minutes to get an instance of OpenMage ready for testing. Forget about XAMPP, WAMP in Windows. The free nature of VMware Workstation allows you to move a virtual machine into many desktops and have a ready to go testing environment.

You can use a test environment in Windows without WSL2, but I do not recommend this configuration because DDEV must be installed in Windows and not inside the Linux distribution. It depends on Mutagen and it is very very slow. Testing in a Linux distribution has many advantages and it is close to the final stage, when you have to move the project into production.

For more information about using DDEV please visit https://docs.openmage.org/developers/tools/ddev/. It is a fantastic tool!

Proxy Connection

When you connect to the Internet through a proxy connection, with or without authentication, because the network administrator has banned the access to certain websites (YouTube, Facebook, TikTok), you have to make some changes to be able to run properly the DDEV-based test environment. Please follow the tutorial I created here #4656.

[addison74]

Those who use PHPStorm as IDE can integrate DDEV in the editor.There is already a plugin that offers more features. For more details visit

https://plugins.jetbrains.com/plugin/18813-ddev-integration

[kiatng]

Question on (Windows) Installing mkcert for Secured Connections
So, I downloaded mkcert following the scoop instructions on https://github.com/FiloSottile/mkcert :

scoop bucket add extras
scoop install mkcert

I cannot connect my steps with this step:

2. Go to the directory where you downloaded the executable file named mkcert-vX.X.X-windows-amd64.exe

Where do I look for the file mkcert-vX.X.X-windows-amd64.exe? What am I missing?

[edit] Got it, the windows executable to install mkcert can be downloaded here: https://github.com/FiloSottile/mkcert/releases

[addison74]

You don't have to use scoop to install mkcert. Just download a release then run the executable in a terminal window, with administrator rights, as mentioned in the tutorial.

[kiatng]

I encountered the following error:

kiat@DESKTOP-7GLIBDK:~/openmage$ ddev composer install
Building project images...
Project images built in 1s.
 Container ddev-openmage-db  Recreate
 Container ddev-openmage-web  Recreate
 Container ddev-openmage-db  Recreated
 Container ddev-openmage-web  Recreated
 Container ddev-openmage-db  Started
 Container ddev-openmage-web  Started
Failed to create certificates for project, check mkcert operation: ERROR: failed to read the CA certificate: unexpected content
; err=exit status 1

What do I do?

[kiatng]

I fixed the ddev launch issue by $ sudo apt install wslu, now it opens the Edge browser. However, I haven't gotten the Not secure issue yet.

[kiatng]

I fixed the Not Secure browsing, ref Discord. It suggested to use the Firefox manual steps described here. In my case, the first 2 steps

Run mkcert -install (you can use the shortcut from the Start Menu for that)
Run mkcert -CAROOT to see the local folder used for the newly-created root certificate authority

are aIl I need. After, I power-down ddev, then start and launch it. Apparently, somehow, I didn't do mkcert -install in Windows, or that I need to install it again.

[addison74]

If you like this development/testing environment, I recommend you to repeat the configuration from scratch several times to familiarize yourself with each step. On a new machine, it doesn't take me more than 15 minutes to configure everything I need and the OpenMage part it takes only a few commands. The tutorial can be fully applied in a Linux distribution, certain steps will no longer be necessary.

Now that you made it works, it's time to familiarize yourself with the DDEV commands. You can install phpmyadmin, cron and many others. Mailpit catches everything that is sent by email. DDEV doesn't only help me with OpenMage, I have several WordPress projects that I am working on. I did not test it with Magento 2.4 yet.

[kiatng]

15 minutes for you is 15 hours for me. Anyway, thanks for your help, without your persistency, I'd given up already.

[addison74]

After a while you will find that you did not waste your time. It would have been a loss to give up. Everyone who wants to give OpenMage a chance and wants to invest minimal effort in testing has this tutorial at their disposal.

[kiatng]

I tried again today. There is a message in VSCode to update DDEV. I did it with sudo apt-get update && sudo apt-get upgrade -y in WSL2 Ubuntu terminal. After verifying the ver with ddev --version, I issue the following in VSCode terminal:

$ ddev --version
ddev version v1.23.4
$ ddev start
$ ddev launch

I get 403 Forbidden in the browser:

.ddev/config.yaml

name: openmage
type: magento
docroot: web
php_version: "8.3"
webserver_type: apache-fpm
xdebug_enabled: false
additional_hostnames: []
additional_fqdns: []
database:
    type: mariadb
    version: "10.4"
use_dns_when_possible: true
composer_version: "2"
web_environment: []
corepack_enable: false
default_container_timeout: "240"

Any idea what I did wrong?

[addison74]

I reviewed this tutorial and installed a test environment on a VM. It works as expected. If you followed all the steps you should not encounter any problem.

I would check the following

1. Run the ddev start command in the OpenMage root directory. This to ensure that you are in the right directory configured by DDEV. From your message I understand that the website loads in the browser, so you have a valid configuration, but it doesn't hurt to check.

2. For sure your problem comes from this line in the DDEV configuration file .ddev/config.yaml

docroot: web

Change it to

docroot: ""

then run the ddev restart command. If you don't have this directory called web, you basically ask the web server to load a root directory that doesn't exist and this is the reason you get the 403 error.

[sreichel]

If "web" is set by default I'll open an issue at DDEV. It should be empty.

[addison74]

I deleted the DDEV configuration file then I used the ddev config command again. The web value is an empty string, as I pointed above.

@sreichel - it is not an issue in DDEV.

[kiatng]

Thanks @addison74 docroot: "" this works. I also deleted the web folder in the root. It had local.xml in the app dir.

[sreichel]

Welcome to DDEV :)

[kiatng]

For PHPMyAdmin, it can be invoked simply with ddev phpmyadmin, which will install it the first time the command is run, and launch it in the browser.

[sreichel]

Useful command ... ddev describe to see all available tools/services.

[addison74]

I guess starting with v1.23.4 there is no need to install phpMyAdmin first using ddev get ddev/ddev-phpmyadmin.

If we missed something we can update it here https://github.com/OpenMage/magento-lts/blob/main/docs/DDEV.md.

[sreichel]

... or here #4156

[sreichel]

6607b0d

[sreichel]

@addison74 can you add it to #4156 ?

[addison74]

Please add it as you want then I can evaluate it.

What's funny is that I made similar tutorials for OpenCart and Prestashop that were quite appreciated. DDEV really solves many problems, I discovered it thanks to you.

[addison74]

Small updates to this article

• VMware Workstation is free to use, no more payment
• Solving the ddev launch command error, the browser is not opening

[addison74]

I will create a separate article for the situation when the computer on which the DDEV test environment is installed is behind a proxy server with authentication. I encountered this situation recently where a corporation allows employees to access the Internet through a proxy server. Now it seems to me easy to implement, but initially it created some issues because the settings have to be made in both Windows and WSL for it to work.

[addison74]

The tutorial can be found here #4656.