[docs] Multiple release prep docs changes, fixes #4411 (#4456)

ddev · Dec 15, 2022 · a8b6469 · a8b6469
1 parent 2c867df
commit a8b6469
Show file tree

Hide file tree

Showing 8 changed files with 68 additions and 87 deletions.
diff --git a/docs/content/users/extend/customization-extendibility.md b/docs/content/users/extend/customization-extendibility.md
@@ -12,7 +12,7 @@ The project's `.ddev/config.yaml` file defines the PHP version to use. The [`php
 
 ## Changing Web Server Type
 
-DDEV supports nginx with php-fpm by default (`nginx-fpm`), and Apache with php-fpm (`apache-fpm`). These can be changed using [`webserver_type`](../configuration/config.md#webserver_type) in `.ddev/config.yaml`, for example `webserver_type: apache-fpm`.
+DDEV supports nginx with php-fpm by default (`nginx-fpm`), and Apache with php-fpm (`apache-fpm`). These can be changed using [`webserver_type`](../configuration/config.md#webserver_type) in `.ddev/config.yaml`, for example `webserver_type: apache-fpm`, then `ddev restart`.
 
 ## Adding Services to a Project
 
@@ -162,15 +162,15 @@ export PATH=$PATH:/var/www/html/somewhereelse/vendor/bin
 
 ## Custom nginx Configuration
 
-When you [`ddev start`](../basics/commands.md#start) using `nginx-fpm`, DDEV creates a configuration customized to your project type in `.ddev/nginx_full/nginx-site.conf`. You can edit and override the configuration by removing the `#ddev-generated` line and doing whatever you need with it. After each change, `ddev start`.
+When you [`ddev restart`](../basics/commands.md#restart) using `nginx-fpm`, DDEV creates a configuration customized to your project type in `.ddev/nginx_full/nginx-site.conf`. You can edit and override the configuration by removing the `#ddev-generated` line and doing whatever you need with it. After each change, `ddev restart`.
 
 You can also have more than one config file in the `.ddev/nginx_full` directory, they will all get loaded when DDEV starts. This can be used for [serving multiple docroots](#multiple-docroots-in-nginx-advanced) and other techniques.
 
 ### Troubleshooting nginx Configuration
 
 * Any errors in your configuration may cause the `web` container to fail and try to restart. If you see that behavior, use [`ddev logs`](../basics/commands.md#logs) to diagnose.
 * You can run `ddev exec nginx -t` to test whether your configuration is valid. (Or run [`ddev ssh`](../basics/commands.md#ssh) and run `nginx -t`.)
-* You can reload the nginx configuration either with [`ddev start`](../basics/commands.md#start) or `ddev exec nginx -s reload`.
+* You can reload the nginx configuration either with [`ddev restart`](../basics/commands.md#restart) or `ddev exec nginx -s reload`.
 * The alias `Alias "/phpstatus" "/var/www/phpstatus.php"` is required for the health check script to work.
 
 !!!warning "Important!"
@@ -194,13 +194,15 @@ For example, to make all HTTP URLs redirect to their HTTPS equivalents you might
     }
 ```
 
+After adding a snippet, `ddev restart` to make it take effect.
+
 ## Custom Apache Configuration
 
 If you’re using [`webserver_type: apache-fpm`](../configuration/config.md#webserver_type) in your `.ddev/config.yaml`, you can override the default site configuration by editing or replacing the DDEV-provided `.ddev/apache/apache-site.conf` configuration.
 
 * Edit the `.ddev/apache/apache-site.conf`.
 * Add your configuration changes.
-* Save your configuration file and run [`ddev start`](../basics/commands.md#start) to reload the project. If you encounter issues with your configuration or the project fails to start, use [`ddev logs`](../basics/commands.md#logs) to inspect the logs for possible Apache configuration errors.
+* Save your configuration file and run [`ddev restart`](../basics/commands.md#restart). If you encounter issues with your configuration or the project fails to start, use [`ddev logs`](../basics/commands.md#logs) to inspect the logs for possible Apache configuration errors.
 * Use `ddev exec apachectl -t` to do a general Apache syntax check.
 * The alias `Alias "/phpstatus" "/var/www/phpstatus.php"` is required for the health check script to work.
 * Any errors in your configuration may cause the `web` container to fail. If you see that behavior, use `ddev logs` to diagnose.

diff --git a/docs/content/users/install/docker-installation.md b/docs/content/users/install/docker-installation.md
@@ -55,47 +55,18 @@ You’ll need a Docker provider on your system before you can [install DDEV](dde
 
     If you’re working inside WSL2, which we recommend, you can [install Docker Engine (docker-ce) inside of it](#docker-ce-inside-windows-wsl2). Otherwise, you can [install Docker Desktop](#docker-desktop-for-windows), which works with both traditional Windows and WSL2.
 
-    ## Docker CE Inside Windows WSL2
+    ### Docker CE Inside Windows WSL2
 
     Many have moved away from using Docker Desktop in favor of the Docker-provided open-source `docker-ce` package inside WSL2.
 
-    Most of the installation is the same as on Linux:
-
-    * If you already have Docker Desktop installed, make sure to disable its integration with your WSL2 distro. In *Resources* → *WSL Integration*, disable integration with the default distro and with your particular distro.
-    * If you don’t already have WSL2, install it with `wsl --install`. This will likely require a reboot.
-    * Run `wsl --set-default-version 2`.
-    * If the `Ubuntu` distro is not already installed and the default distro (see `wsl -l -v`) then install it with `wsl --install Ubuntu`.
-    * Install `docker-ce` in WSL2 using the normal Linux instructions. For Debian/Ubuntu, run the following inside the WSL2 distro:
-        ```bash
-        sudo apt-get remove docker docker-engine docker.io containerd runc
-        sudo apt-get update && sudo apt-get install ca-certificates curl gnupg lsb-release
-        curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
-        echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
-        sudo apt-get update && sudo apt-get -y install docker-ce docker-ce-cli containerd.io
-        sudo groupadd docker && sudo usermod -aG docker $USER
-        ```
-    * You have to start `docker-ce` yourself on login, or use a script to automate it. To have it start on entry to Git Bash, add a startup line to your (Windows-side) `~/.bashrc` with:
-        ```bash
-        echo "wsl.exe -u root service docker status > /dev/null || wsl.exe -u root service docker start > /dev/null" >> ~/.bashrc
-        ```
-
-        `source ~/.bashrc` to start immediately, or it should start with your next Git Bash session.
-
-    * [Install mkcert](https://github.com/FiloSottile/mkcert#windows) on the Windows side, which may be easiest with [Chocolatey](https://chocolatey.org/install): 
-        * In an administrative PowerShell: 
-            ```
-            Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.        ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/        install.ps1'))
-            ```
-        * In an administrative PowerShell: `choco install -y mkcert`.
-        * In an administrative PowerShell, run `mkcert -install` and follow prompts to install the Certificate Authority.
-        * In an administrative PowerShell, run `setx CAROOT "$(mkcert -CAROOT)"; If ($Env:WSLENV -notlike "*CAROOT/up:*") { setx WSLENV "CAROOT/up:$Env:WSLENV" }`. This will set WSL2 to use the Certificate Authority installed on the Windows side.
-        * Double-check in Ubuntu (or your distro): `echo $CAROOT` should show something like `/mnt/c/Users/<you>/AppData/Local/mkcert`.
-        * Inside your WSL2 distro, `mkcert -install`.
+    The instructions for [DDEV Installation in WSL2](ddev-installation.md#windows-wsl2) include Docker CE setup and a script that does almost all the work. Please use those.
 
     ### Docker Desktop for Windows
 
     Docker Desktop for Windows can be downloaded via [Chocolatey](https://chocolatey.org/install) with `choco install docker-desktop` or it can be downloaded from [docker.com](https://www.docker.com/products/docker-desktop). It has extensive automated testing with DDEV, and works with DDEV both on traditional Windows and in WSL2.
 
+    Full instructions for installing DDEV with Docker Desktop on WSL2 are provided in the [WSL2 DDEV Installation](ddev-installation.md#windows-wsl2) section.
+
 === "Linux"
 
     ## Linux

diff --git a/docs/content/users/providers/platform.md b/docs/content/users/providers/platform.md
@@ -5,7 +5,7 @@ DDEV provides integration with the [Platform.sh Website Management Platform](htt
 !!!tip
     Consider using `ddev get platformsh/ddev-platformsh` ([platformsh/ddev-platformsh](https://github.com/platformsh/ddev-platformsh)) for more complete Platform.sh integration.
 
-DDEV’s Platform.sh integration pulls database and files from an existing Platform.sh site/environment into your local system so you can develop locally.
+DDEV’s Platform.sh integration pulls databases and files from an existing Platform.sh site/environment into your local system so you can develop locally.
 
 ## Platform.sh Global Configuration
 
@@ -39,11 +39,11 @@ web_environment:
         ```
 
 3. Run [`ddev restart`](../basics/commands.md#restart).
-4. Run `ddev pull platform`. After you agree to the prompt, the current upstream database and files will be downloaded.
+4. Run `ddev pull platform`. After you agree to the prompt, the current upstream databases and files will be downloaded.
 5. Optionally use `ddev push platform` to push local files and database to Platform.sh. The [`ddev push`](../basics/commands.md#push) command can potentially damage your production site, so we don’t recommend using it.
 
 If you have more than one database on your Platform.sh project, you'll need to choose which one you want to use
-as the 'db' primary database on DDEV, and that will be the one pulled or pushed.
+as the 'db' primary database on DDEV, and that one will be pulled to the database named `db`.
 Do this by setting PLATFORM_PRIMARY_RELATIONSHIP, for example,
 
 ```

diff --git a/docs/content/users/quickstart.md b/docs/content/users/quickstart.md
@@ -144,22 +144,6 @@ DDEV comes ready to work with any PHP project, and has deeper support for severa
 
     ## Drupal
 
-    === "Drupal 9"
-
-        ### Drupal 9 via Composer
-
-        ```bash
-        mkdir my-drupal9-site
-        cd my-drupal9-site
-        ddev config --project-type=drupal9 --docroot=web --create-docroot
-        ddev start
-        ddev composer create "drupal/recommended-project"
-        ddev composer require drush/drush
-        ddev drush site:install -y
-        ddev drush uli
-        ddev launch
-        ```
-
     === "Drupal 10"
 
         ### Drupal 10 via Composer
@@ -171,15 +155,29 @@ DDEV comes ready to work with any PHP project, and has deeper support for severa
         cd my-drupal10-site
         ddev config --project-type=drupal10 --docroot=web --create-docroot
         ddev start
-        ddev composer create drupal/recommended-project:^10@rc
+        ddev composer create drupal/recommended-project
         ddev composer require drush/drush
-        ddev drush site:install -y
+        ddev drush site:install --account-name=admin --account-pass=admin -y
         ddev drush uli
         ddev launch
         ```
 
-        !!!tip
-            As Drupal 10 moves from beta and to release, you’ll want to change the tag from `^10@rc` to `^10`.
+
+    === "Drupal 9"
+
+        ### Drupal 9 via Composer
+
+        ```bash
+        mkdir my-drupal9-site
+        cd my-drupal9-site
+        ddev config --project-type=drupal9 --docroot=web --create-docroot
+        ddev start
+        ddev composer create "drupal/recommended-project:^9"
+        ddev composer require drush/drush
+        ddev drush site:install --account-name=admin --account-pass=admin -y
+        ddev drush uli
+        ddev launch
+        ```
 
     === "Drupal 6/7"
 

diff --git a/docs/content/users/topics/phpstorm.md b/docs/content/users/topics/phpstorm.md
@@ -58,19 +58,19 @@ This part is not done for you by the integration plugin.
 
 It’s possible to use PhpStorm with DDEV on WSL2 in at least three different ways:
 
-1. Run PhpStorm in Windows as usual, opening the project on the WSL2 filesystem at `\\wsl$\<distro>` (e.g. `\\wsl$\Ubuntu`). PhpStorm is slow to index files and is slow to respond to file changes in this mode.
-2. Enabling X11 on Windows and running PhpStorm inside WSL2 as a Linux app. PhpStorm works fine this way, but it’s yet another complexity to manage and requires enabling X11 on your Windows system, which is fairly simple.
-3. [JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/) runs PhpStorm on WSL2 (or anywhere else) but displays it in a in your Gateway app. It requires configuring `sshd` in WSL2 and either auto-starting it with `/etc/wsl.conf` (Windows 11) or starting it manually.
+1. Run PhpStorm in Windows as usual, opening the project on the WSL2 filesystem at `\\wsl$\<distro>` (e.g. `\\wsl$\Ubuntu`). PhpStorm is slow to index files but can be slow to respond to file changes in this mode, although it's adequate for many people.
+2. "Remote Development" in PhpStorm 2022.3+, which has explicit support for WSL2 and actually runs a PhpStorm instance on WSL2.
+3. Enabling X11 on Windows and running PhpStorm inside WSL2 as a Linux app. PhpStorm works fine this way; it does require WSL2 graphics support, which is now available on all Windows 10 and Windows 11 systems.
 
-We’ll walk through the first two of these approaches.
+We’ll walk through each of these approaches.
 
 ### Basics
 
 - Start with a working DDEV/WSL2 setup as described in the [docs](../install/ddev-installation.md). Until that’s all working it doesn’t help to go farther.
 
 - If you haven’t used Xdebug with DDEV and PhpStorm before, you’ll want to read the [step debugging instructions](../debugging-profiling/step-debugging.md).
 
-- For usable performance, your project should be in `/home` inside WSL2, which is on the Linux filesystem. Although you could keep your project on the Windows filesystem and access it in WSL2 via `/mnt/c`, the performance is even worse than native Windows. It does work though, but don’t do it. You’ll be miserable.
+- Your project absolutely must be in `/home` inside WSL2, which is on the Linux filesystem. Although you could keep your project on the Windows filesystem and access it in WSL2 via `/mnt/c`, the performance is even worse than native Windows. It does work though, but don’t do it. You’ll be miserable.
 
 ### PhpStorm Running On Windows Side and Using Docker Desktop
 
@@ -89,28 +89,30 @@ Debugging should be working. You can step through your code, set breakpoints, vi
 
 Set the PhpStorm terminal path (*Settings* → *Tools* → *Terminal* → *Shell Path*) to `C:\Windows\System32\wsl.exe`. That way when you use the terminal Window in WSL2 it’s using the Bash shell in WSL2.
 
+### PhpStorm with "Remote Development" option
+
+1. Open your WSL2 project using *File* → *Remote Development* → *WSL*: Choose the distro and then the project.
+2. For xdebug you'll want to use `ddev config global --xdebug-ide-location=wsl2` because essentially the IDE is running inside WSL2 (and listening there).
+3. Use `ddev xdebug on` as normal; test with a simple breakpoint in your `index.php`.
+
 ### PhpStorm Inside WSL2 in Linux
 
-1. On Windows 11 you don’t need to install an X11 server, because [WSLg](https://github.com/microsoft/wslg) is included by default. On older Windows 10, Install X410 from the Microsoft Store, launch it, configure in the system tray with “Windowed Apps”, “Allow public access”, “DPI Scaling” → ”High quality”. You can any other X11 server, this is just one possibility.
-2. Temporarily disable your Windows firewall. You can re-enable it after you get everything working.
-3. If you’re on older Windows 10, in the WSL2 terminal `export DISPLAY=$(awk '/^nameserver/ {print $2; exit;}' </etc/resolv.conf):0.0` (You’ll want to add this to your `.profile` in WSL2). This sets the X11 DISPLAY variable to point to your Windows host side. On Windows 11 this “just works” and you don’t need to do anything here.
-4. Install the DDEV apt repository:
+1. On Windows 10 or 11 get "Windows Subsystem for Linux" from the Microsoft Store, which now includes graphical support.
+2. Edit `/etc/wsl.conf` to systemd support, which allows for installing PhpStorm with snap, see [details about WSL2 and systemd](https://devblogs.microsoft.com/commandline/systemd-support-is-now-available-in-wsl/):
 
-    ```bash
-    curl -fsSL https://apt.fury.io/drud/gpg.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/ddev.gpg > /dev/null
-    echo "deb [signed-by=/etc/apt/trusted.gpg.d/ddev.gpg] https://apt.fury.io/drud/ * *" | sudo tee /etc/apt/sources.list.d/ddev.list
-    sudo apt update && sudo apt install -y ddev
+    ```
+    [boot]
+    systemd=true
     ```
 
-5. On Windows 11, `sudo apt-get update && sudo apt-get install ddev`. On older Windows 10, `sudo apt-get update && sudo apt-get install ddev libatk1.0 libatk-bridge2.0 libxtst6 libxi6 libpangocairo-1.0 libcups2 libnss3 xdg-utils x11-apps`
-6. On older Windows 10, run `xeyes`. You should see the classic X11 play app “xeyes” on the screen. <kbd>CTRL</kbd> + <kbd>C</kbd> to exit. This is just a test to make sure X11 is working.
-7. Download and untar PhpStorm for Linux from [JetBrains](https://www.jetbrains.com/phpstorm/download/#section=linux). You need the Linux app.
-8. Run `bin/phpstorm.sh &`.
-9. In PhpStorm, under *Help* → *Edit Custom VM Options*, add another line: `-Djava.net.preferIPv4Stack=true`. This makes PhpStorm listen for Xdebug using IPv4; for some reason the Linux version of PhpStorm defaults to using only IPv6, and Docker Desktop doesn’t support IPv6.
-10. Restart PhpStorm with *File* → *Exit* and run `bin/phpstorm.sh &` again.
-11. Use `ddev start` and `ddev xdebug on`.
-12. Click the Xdebug listen button in PhpStorm (the little phone icon) to make it start listening.
-13. Set a breakpoint on or near the first line of your `index.php`.
-14. Visit the project with a web browser or cURL. You should get a popup asking for mapping of the host-side files to the in-container files. Make sure `/home/<you>/.../<yourproject>` is mapped to `/var/www/html`.
+3. `wsl --shutdown` on the Windows side and wait 10 seconds, then restart your distro.
+4. In WSL2, `sudo snap install --classic phpstorm`.
+5. DDEV should already be installed as described in [DDEV installation](../install/ddev-installation.md#windows-wsl2).
+6. `ddev config global --xdebug-ide-location=wsl2` to tell DDEV that the IDE is listening in WSL2 as opposed to listening on the Windows side.
+7. Start PhpStorm, `phpstorm &`.
+8. Use `ddev start` and `ddev xdebug on`.
+9. Click the Xdebug listen button in PhpStorm (the little phone icon) to make it start listening.
+10. Set a breakpoint on or near the first line of your `index.php`.
+11. Visit the project with a web browser or cURL. You should get a popup asking for mapping of the host-side files to the in-container files. Make sure `/home/<you>/.../<yourproject>` is mapped to `/var/www/html`.
 
 Debugging should be working! You can step through your code, set breakpoints, view variables, etc.
diff --git a/pkg/ddevapp/config.go b/pkg/ddevapp/config.go
@@ -578,7 +578,7 @@ func (app *DdevApp) CheckCustomConfig() {
 		}
 	}
 	if customConfig {
-		util.Warning("Custom configuration takes effect when the container is created.\nShould something go wrong and no effect be visible use 'ddev restart'.")
+		util.Warning("Custom configuration takes effect when the container is created.\nUse 'ddev restart' for force it to take effect.")
 	}
 
 }

diff --git a/pkg/ddevapp/dotddev_assets/providers/platform.yaml b/pkg/ddevapp/dotddev_assets/providers/platform.yaml
@@ -23,7 +23,7 @@
 # 5. Run `ddev pull platform`. After you agree to the prompt, the current upstream database and files will be downloaded.
 # 6. Optionally use `ddev push platform` to push local files and database to platform.sh. Note that `ddev push` is a command that can potentially damage your production site, so this is not recommended.
 
-# If you have more than one database on your Platform.sh proect,
+# If you have more than one database on your Platform.sh project,
 # you will likely to choose which one you want to use
 # as the primary database ('db').
 # Do this by setting PLATFORM_PRIMARY_RELATIONSHIP, for example, `ddev config --web-environment-add=PLATFORM_PRIMARY_RELATIONSHIP=main`