From 8b6644bbfcf89b8a0253d5b0ab5adfffd84e5a2a Mon Sep 17 00:00:00 2001 From: bidi Date: Thu, 24 Sep 2026 18:32:58 +0300 Subject: [PATCH 1/2] Add Editor Integration and WSL Configuration pages The biggest content gap versus general "Linux dev box on WSL" guides was editor integration: nothing covered VS Code Remote-WSL, PhpStorm's WSL interpreter, or Xdebug (which the playbook doesn't install). Filesystem placement/performance, .wslconfig tuning, and backup/ portability (wsl --export/--import) were similarly absent. - Add docs/book/v2/editor-integration.md: VS Code Remote-WSL (code .), PhpStorm WSL interpreter setup, Xdebug install + config for both editors, and PHPUnit runner setup. - Add docs/book/v2/wsl-configuration.md: why projects should live in the WSL filesystem rather than /mnt/c, opening a WSL project from Windows (\\wsl.localhost, explorer.exe .), .wslconfig tuning (memory/CPU/swap/vmIdleTimeout/mirrored networking), and wsl --export/--import as the non-destructive alternative to the already-documented --unregister. - Wire both into mkdocs.yml's v2 nav, between Virtualhosts and FAQ. --- docs/book/v2/editor-integration.md | 84 ++++++++++++++++++++++++++++++ docs/book/v2/wsl-configuration.md | 75 ++++++++++++++++++++++++++ mkdocs.yml | 2 + 3 files changed, 161 insertions(+) create mode 100644 docs/book/v2/editor-integration.md create mode 100644 docs/book/v2/wsl-configuration.md diff --git a/docs/book/v2/editor-integration.md b/docs/book/v2/editor-integration.md new file mode 100644 index 0000000..21ca224 --- /dev/null +++ b/docs/book/v2/editor-integration.md @@ -0,0 +1,84 @@ +# Editor Integration + +## Summary + +Connect your editor of choice (VS Code or PhpStorm) directly to your **AlmaLinux 10** environment, and set up Xdebug for step debugging. + +> This assumes you've already completed [Setup Packages](setup/setup-packages.md) and have at least one project running under a [virtualhost](virtualhosts/overview.md). + +## VS Code (Remote - WSL) + +Install the [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) extension in VS Code on Windows. + +Then, from inside **AlmaLinux 10**, move to your project's directory and run: + +```shell +code . +``` + +This opens VS Code connected to your **AlmaLinux 10** distro - notice the green remote indicator in the bottom-left corner. Every extension, terminal, and file operation now runs using the Linux binaries inside AlmaLinux 10, not the Windows ones, which matters for anything that shells out to `php`, `composer`, or `node`. + +> The first time you run `code .` from a new distro, VS Code Server is downloaded and installed automatically inside AlmaLinux 10 - this can take a minute or two. + +## PhpStorm (WSL interpreter) + +PhpStorm can also run against the PHP interpreter inside AlmaLinux 10 directly, rather than a local Windows PHP install. + +1. Open your project in PhpStorm. +2. Go to `Settings` -> `PHP`. +3. Next to `CLI Interpreter`, click `...` and add a new interpreter. +4. Choose `From WSL`, select the `AlmaLinux-10` distro, and point it at `/usr/bin/php`. +5. Confirm and apply. + +PhpStorm can now index, run, and debug using the same PHP install the playbook provisioned, instead of a separate Windows copy. + +> If your project files live inside the WSL filesystem (the default and recommended location - see [WSL Configuration](wsl-configuration.md)), open the project from its `\\wsl.localhost\AlmaLinux-10\...` path in PhpStorm so file watching and indexing stay fast. + +## Xdebug + +Xdebug isn't installed by the playbook. To add it: + +```shell +sudo dnf install php-pecl-xdebug -y +``` + +Then configure it (as root) by editing the Xdebug ini file: + +```shell +sudo nano /etc/php.d/15-xdebug.ini +``` + +Add or adjust: + +```text +zend_extension=xdebug.so +xdebug.mode=debug +xdebug.start_with_request=yes +xdebug.client_host=127.0.0.1 +xdebug.client_port=9003 +``` + +Restart PHP-FPM for the change to take effect: + +```shell +sudo systemctl restart php-fpm +``` + +### VS Code + +Install the `PHP Debug` extension, then add a `Listen for Xdebug` launch configuration on port `9003`. Start listening, then request your project's URL in the browser - the debugger should stop at your breakpoints. + +### PhpStorm + +Go to `Settings` -> `PHP` -> `Debug`, confirm the Xdebug port is `9003`, then click the "Start listening for PHP Debug connections" icon in the toolbar and request your project's URL in the browser. + +## PHPUnit + +Both editors can run PHPUnit using the same WSL-side PHP and Composer install: + +* **VS Code**: install a PHPUnit test-runner extension once connected via Remote - WSL, and point it at your project's `vendor/bin/phpunit`. +* **PhpStorm**: go to `Settings` -> `PHP` -> `Test Frameworks`, add a PHPUnit configuration using the WSL interpreter configured above and your project's `vendor/bin/phpunit`. + +## Next step + +See [WSL Configuration](wsl-configuration.md) for where to put your project files and how to tune WSL's resource usage, or jump to the [FAQ](faq.md) for common troubleshooting. diff --git a/docs/book/v2/wsl-configuration.md b/docs/book/v2/wsl-configuration.md new file mode 100644 index 0000000..db39552 --- /dev/null +++ b/docs/book/v2/wsl-configuration.md @@ -0,0 +1,75 @@ +# WSL Configuration + +## Summary + +Where to put your project files, how to open them from Windows, how to tune WSL 2's resource usage, and how to back up or move your distro. + +## Where to put your project files + +Keep your projects inside the WSL filesystem - for example under `/var/www/`, which is exactly where this playbook creates your virtualhosts. Avoid working with projects stored under `/mnt/c/...` (or any other Windows drive mounted into WSL): crossing filesystems this way can significantly slow down file-heavy operations like `composer install`, `npm install`, or a framework's file-watcher. + +> If you cloned a project onto `C:\` before setting up WSL, move or re-clone it into your AlmaLinux 10 home directory or `/var/www` instead. + +## Opening a WSL project from Windows + +To browse your **AlmaLinux 10** files from Windows File Explorer, open: + +```text +\\wsl.localhost\AlmaLinux-10\var\www\ +``` + +(older WSL versions use `\\wsl$\AlmaLinux-10\...` instead - both work). + +From inside AlmaLinux 10, you can also open the current directory in Windows File Explorer directly: + +```shell +explorer.exe . +``` + +## `.wslconfig` + +WSL 2 runs inside a lightweight VM, and by default it can use most of your machine's memory and grow its virtual disk indefinitely. You can cap this with a `.wslconfig` file at `C:\Users\\.wslconfig` (created from Windows, not inside AlmaLinux 10): + +```text +[wsl2] +memory=8GB +processors=4 +swap=2GB +vmIdleTimeout=60000 +networkingMode=mirrored +``` + +* `memory` / `processors`: cap how much RAM/CPU the WSL VM can use. +* `swap`: swap file size inside the VM. +* `vmIdleTimeout`: milliseconds of inactivity before the VM is torn down (frees memory when you're not using WSL). +* `networkingMode=mirrored`: mirrors your Windows network interfaces into WSL, which can fix some VPN/corporate-network connectivity issues. + +Apply changes with: + +```shell +wsl --shutdown +``` + +then reopen **AlmaLinux 10**. + +> The VM's virtual disk (VHDX) only grows - it doesn't shrink automatically as you delete files. See Microsoft's guide on compacting a WSL disk if it grows larger than expected. + +## Backup and portability + +`wsl --unregister AlmaLinux-10` (documented in [Install AlmaLinux 10](setup/installation.md)) deletes the distro and everything in it - it's a reset, not a backup. + +To back up or move your environment instead, export it to a single file: + +```shell +wsl --export AlmaLinux-10 alma-linux-10-backup.tar +``` + +And restore it (to the same machine or a different one) with: + +```shell +wsl --import AlmaLinux-10 C:\WSL\AlmaLinux-10 alma-linux-10-backup.tar +``` + +## Next step + +See [Editor Integration](editor-integration.md) to connect VS Code or PhpStorm, or jump to the [FAQ](faq.md) for common troubleshooting. diff --git a/mkdocs.yml b/mkdocs.yml index 7a82379..bcdcb1c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -18,6 +18,8 @@ nav: - Virtualhosts: - Overview: v2/virtualhosts/overview.md - Create virtualhost: v2/virtualhosts/create-virtualhost.md + - Editor Integration: v2/editor-integration.md + - WSL Configuration: v2/wsl-configuration.md - FAQ: v2/faq.md - v1: - Terminal: v1/terminal.md From 10287539332b8714ad79a80d60d10f739ee0e45b Mon Sep 17 00:00:00 2001 From: bidi Date: Fri, 25 Sep 2026 13:39:05 +0300 Subject: [PATCH 2/2] updated editor page Signed-off-by: bidi --- docs/book/v2/editor-integration.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/book/v2/editor-integration.md b/docs/book/v2/editor-integration.md index 21ca224..947c402 100644 --- a/docs/book/v2/editor-integration.md +++ b/docs/book/v2/editor-integration.md @@ -22,7 +22,7 @@ This opens VS Code connected to your **AlmaLinux 10** distro - notice the green ## PhpStorm (WSL interpreter) -PhpStorm can also run against the PHP interpreter inside AlmaLinux 10 directly, rather than a local Windows PHP install. +You install PhpStorm normally on Windows, but configure it to use the PHP interpreter inside AlmaLinux 10 instead of installing PHP on Windows. 1. Open your project in PhpStorm. 2. Go to `Settings` -> `PHP`. @@ -32,7 +32,8 @@ PhpStorm can also run against the PHP interpreter inside AlmaLinux 10 directly, PhpStorm can now index, run, and debug using the same PHP install the playbook provisioned, instead of a separate Windows copy. -> If your project files live inside the WSL filesystem (the default and recommended location - see [WSL Configuration](wsl-configuration.md)), open the project from its `\\wsl.localhost\AlmaLinux-10\...` path in PhpStorm so file watching and indexing stay fast. +> Your project files are located inside the WSL filesystem (the default and recommended location - see [WSL Configuration](wsl-configuration.md)). +> You open the project from its `\\wsl.localhost\AlmaLinux-10\...` path in PhpStorm so file watching and indexing stay fast. ## Xdebug