Skip to content

Commit 953eb1f

Browse files
sreichelsreichel
authored
DOCS: added ddev docs for windows (#4611)
1 parent 688bdea commit 953eb1f

File tree

4 files changed

+174
-5
lines changed

4 files changed

+174
-5
lines changed

‎docs/content/blog/.authors.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@ authors:
33
name: OpenMage
44
description: Community
55
avatar: https://avatars.githubusercontent.com/u/57708
6+
addison74:
7+
name: Addison
8+
description: Maintainer
9+
avatar: https://avatars.githubusercontent.com/u/8360474
610
colinmollenhour:
711
name: Colin Mollenhour
812
description: Maintainer

‎docs/content/blog/posts/guides/2024-02-17-ddev-windows-10.md

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
---
2+
title: Test Environment for OpenMage in Windows 10 Based on DDEV
3+
draft: false
4+
date: 2024-08-17
5+
authors:
6+
- addison74
7+
categories:
8+
- Guides
9+
tags:
10+
- DDEV
11+
- Windows 10
12+
---
13+
14+
# Test Environment for OpenMage in Windows 10 Based on DDEV
15+
16+
This guide will be updated frequently.
17+
18+
<!-- more -->
19+
20+
### IMPORTANT
21+
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.
22+
23+
You need at least 8 GB of memory to run (Docker + PHPStorm) decent. I recommend a machine with 16 GB.
24+
25+
![windows_1909](https://github.com/OpenMage/magento-lts/assets/8360474/33c7605e-b9ff-46a5-b960-0e2aabb4dc77)
26+
27+
### (Windows) Installing the Windows Terminal Application
28+
1. Open the `Microsoft Store` application and search for `Windows Terminal`
29+
2. Choose the first result then press the `Get` button
30+
31+
![windows_terminal](https://github.com/OpenMage/magento-lts/assets/8360474/fbcb31fa-3582-4372-8acd-48f4956d6d30)
32+
33+
If you use PHPStorm, at the bottom there is a tab called `Terminal`. Here you can run commands in the Linux distribution too.
34+
35+
![phpstorm_terminal](https://github.com/OpenMage/magento-lts/assets/8360474/cca5b48d-dd5b-4d80-8664-a4f99ee9f960)
36+
37+
### (Windows) Installing WSL2 (Windows Subsystem for Linux 2)
38+
**The Installation Tutorial**
39+
https://pureinfotech.com/install-windows-subsystem-linux-2-windows-10/
40+
41+
**Useful Commands**
42+
https://learn.microsoft.com/en-us/windows/wsl/
43+
```
44+
wsl --install
45+
wsl --version
46+
wsl --update
47+
wsl --list --online
48+
wsl --install -d DISTRO-NAME
49+
wsl --set-version <distro name> 2
50+
```
51+
52+
**Advanced Settings**
53+
https://learn.microsoft.com/en-us/windows/wsl/wsl-config#configure-global-options-with-wslconfig
54+
55+
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
56+
57+
```
58+
[wsl2]
59+
memory=4GB # Limits VM memory in WSL 2 up to 4 GB
60+
processors=6
61+
```
62+
63+
### (Windows) Installing a Linux Distribution
64+
**Variant 1**
65+
1. Open the `Command Prompt` application as Administrator
66+
2. Get the distributions list `wsl --list --online`
67+
3. Install a distribution `wsl --install -d Ubuntu-20.04`
68+
4. Reboot the system
69+
70+
**Variant 2**
71+
1. Open the `Microsoft Store` application and search for Ubuntu
72+
2. Install an LTS version, for example Ubuntu 20.04.6 LTS
73+
3. Reboot the system
74+
75+
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).
76+
77+
![terminal](https://github.com/OpenMage/magento-lts/assets/8360474/b88fe7ae-4d86-4cba-a239-01c06a685bec)
78+
79+
### (Windows) Installing Docker
80+
https://docs.docker.com/desktop/install/windows-install/
81+
82+
1. Download the installation file `Docker Desktop Installer.exe` and run it as Administrator
83+
2. During installation check the option `Use WSL 2 instead of Hyper-V (recommended)`
84+
3. Reboot the system
85+
86+
### (Windows) Installing mkcert for Secured Connections
87+
https://github.com/FiloSottile/mkcert
88+
89+
1. Download the latest Windows release
90+
2. Open the `Terminal` application as Administrator
91+
3. Go to the directory where you downloaded the executable file named `mkcert-vX.X.X-windows-amd64.exe`
92+
4. Run `mkcert-vX.X.X-windows-amd64.exe --install`
93+
5. In the popup window, where you are asked if you want to install the certificate, press `Yes`
94+
95+
### (Windows) Linux distribution drive mapping
96+
97+
1. Open the `Windows Explorer` application
98+
2. On the left side open the `Linux` path and select `Ubuntu-20.04`
99+
3. Right-click and select `Map network drive...` from the menu. Choose a letter, for example Z:
100+
101+
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.
102+
103+
![windows_explorer](https://github.com/OpenMage/magento-lts/assets/8360474/97dacd28-a316-4312-8f5a-1eb67b796d07)
104+
105+
### (Windows) PHPStorm
106+
107+
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.
108+
109+
![new_project](https://github.com/OpenMage/magento-lts/assets/8360474/b408b23c-0128-4887-abc8-30e7133e4fb3)
110+
111+
### (Linux) Installing DDEV
112+
https://ddev.readthedocs.io/en/latest/users/install/ddev-installation/
113+
114+
1. Open the `Terminal` application and choose a new tab with Ubuntu
115+
2. Bring all the packages up to date Ubuntu `sudo apt update && sudo apt upgrade -y`
116+
3. Install DDEV according to the instructions
117+
118+
### (Linux) Copying mkcert Certificates from Windows to Linux
119+
120+
**Variant 1**
121+
1. Open the `Terminal` application and choose a new tab with Ubuntu
122+
2. Create the path `mkdir -p /home/<user_name/.local/share/mkcert`
123+
3. Run `cp /mnt/c/Users/<User Name>/AppData/Local/mkcert/* /home/<user_name>/.local//share/mkcert/`
124+
125+
**Variant 2**
126+
1. Run the `Windows Explorer` application as administrator
127+
2. Copy the files `rootCA.pem` and `rootCA-key.pem` from `C:\Users\<User Name>\AppData\Local\mkcert`
128+
3. Create the path in Linux > Ubuntu-20.04 `/home/<user_name/.local/share/mkcert`
129+
4. Paste them in the `mkcert` directory
130+
131+
### (Linux) Installing OpenMage
132+
First make sure that the `Docker Desktop` application is running in Windows.
133+
134+
1. Open the `Terminal` application and choose a new tab with Ubuntu
135+
2. Create the path `mkdir -p /home/<user_name>/openmage`
136+
3. Clone the OpenMage repository `git clone https://github.com/OpenMage/magento-lts.git /home/<user_name>/openmage`
137+
4. Go to the directory `/home/<user_name>/openmage`
138+
5. Run the following DDEV commands. The first command configures the project, the second installs OpenMage dependencies, the third installs Magento Sample Data.
139+
140+
```
141+
ddev config
142+
ddev composer install
143+
ddev openmage-install -s -k
144+
```
145+
146+
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
147+
148+
```
149+
php_version: "8.3"
150+
webserver_type: apache-fpm
151+
```
152+
153+
7. Run the following DDEV commands to load the project in the browser window with a secured connection
154+
155+
```
156+
ddev start
157+
ddev launch
158+
```
159+
160+
For more information about using DDEV please visit https://github.com/OpenMage/magento-lts/blob/main/docs/DDEV.md. It is a fantastic tool!
161+
162+
### CONCLUSION
163+
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.
164+
165+
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 moving the project into production.

‎docs/content/developers/tools/ddev.md

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,12 @@ tags:
88
[DDEV](https://ddev.com) is a powerful tool to set up and manage local PHP development environments.
99
It is a Docker-based wrapper that provides many useful features for developers out of the box.
1010

11-
!!! info
12-
If you prefer a simpler development environment with no dependencies aside from Docker, see the
13-
[Docker Compose](/developers/tools/oneline) guide instead.
11+
!!! info "Docker only"
12+
For development environment without dependencies aside from Docker, see the
13+
[Docker Compose](/developers/tools/oneline) guide.
1414

1515
!!! info "Test Environment for OpenMage in Windows 10 Based on DDEV"
16-
17-
See https://github.com/OpenMage/magento-lts/discussions/3839
16+
For development environment with Windows 10, see this [guide](/blog/2024/08/17/test-environment-for-openmage-in-windows-10-based-on-ddev/).
1817

1918
## Using phpMyAdmin
2019

‎mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -205,6 +205,7 @@ nav:
205205
- blog/posts/guides/2023-01-09-dynamic-blocks.md
206206
- blog/posts/guides/2022-08-17-observer.md
207207
- blog/posts/guides/2023-05-01-customize-your-openmage.md
208+
- blog/posts/guides/2024-02-17-ddev-windows-10.md
208209
- 'Documentation':
209210
- developers/mkdocs.md
210211
- 'Modules':

0 commit comments

Comments
 (0)